Documentação
Princípios de Engenharia de Software em Python
Adam Spannbauer
Machine Learning Engineer at Eastman
Documentação em Python
- Comentários
# Calcula o quadrado do número x
- Docstrings
"""Calcula o quadrado do número x
:param x: número a ser elevado ao quadrado
:return: x ao quadrado
>>> square(2)
4
"""
Comentários
# Este é um comentário válido
x = 2
y = 3 # Este também é um comentário válido
# Você não me vê a menos que olhe o código-fonte# Olá futuros colaboradores!!
Comentários eficazes
Comentando 'o quê'
# Define pessoas como 5
pessoas = 5
# Multiplica pessoas por 3
pessoas * 3
Comentando 'por quê'
# Haverá 5 pessoas na festa
pessoas = 5
# Precisamos de 3 pedaços de pizza por pessoa
pessoas * 3
Docstrings
def function(x):
"""Descrição geral da função
Detalhes adicionais sobre a função
Docstrings
def function(x):
"""Descrição geral da função
Detalhes adicionais sobre a função
:param x: descrição do parâmetro x
:return: descrição do valor de retorno
Página de exemplo gerada a partir de uma docstring no pacote Flask.
Docstrings
def function(x):
"""Descrição geral da função
Detalhes adicionais sobre a função
:param x: descrição do parâmetro x
:return: descrição do valor de retorno
>>> # Exemplo de uso da função
Saída esperada do exemplo de uso
"""
# código da função
Exemplo de docstring
def square(x):
"""Calcula o quadrado do número x
:param x: número a ser elevado ao quadrado
:return: x ao quadrado
>>> square(2)
4
"""
# `x * x` é mais rápido que `x ** 2`
# referência: https://stackoverflow.com/a/29055266/5731525
return x * x
Saída do exemplo de docstring
help(square)
square(x)
Calcula o quadrado do número x
:param x: número a ser elevado ao quadrado
:return: x ao quadrado
>>> square(2)
4
Vamos Praticar
Princípios de Engenharia de Software em Python
