PEP 8 - Guia de estilo para código Python
Este artigo é uma tradução/adaptação da PEP 8 - Style Guide for Python Code, de Guido van Rossum e Barry Warsaw, que mostra as convenções para escrever código Python.
Parte 5: Comentários e docstrings
Comentários
Comentários contraditórios são piores que a falta de comentários. Sempre tenha como prioridade atualizar os comentários quando o código muda.Comentários devem ser orações completas. Se o comentário é uma frase ou oração, sua primeira letra deve ser maiúscula, a não ser que seja um identificador que comece com minúscula (nunca altere a caixa dos identificadores).
Comentários de bloco normalmente consistem em um ou mais parágrafos com orações completas.
Você deve usar dois espaços após o fim de uma oração.
Programadores de países não anglófonos devem escrever os comentários em inglês, a não ser que tenham 120% de certeza que seu código nunca vai ser lido por pessoas que não falam sua língua.
Um comentário na mesma linha de um statement (inline) deve ter ao menos dois espaços de distância do statement e deve começar com um '#', um espaço e o texto.
Comentários inline são desnecessários e, de fato, distrativos quando mostram o óbvio. Não faça isso:
x = x + 1 # Incrementa x
Mas, às vezes, isso é útil:
x = x + 1 # Compensar para fronteira
Docstrings
Convenções para escrever docstrings estão na PEP 257.Escreva docstrings para todos os módulos, funções, classes e métodos públicos. Elas não são necessárias para métodos não públicos, mas você deve ter um comentário que descreve o que o método faz. Este comentário deve aparecer logo após o statement def.
A PEP 257 descreve como escrever docstrings. Note que o mais importante é que o """ que terminam uma docstring de múltiplas linhas deve ter sua própria linha, de preferência, precedida por uma linha em branco. Exemplo:
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
Optional plotz says to frobnicate the bizbaz first.
"""
Para docstrings de uma linha, pode-se colocar o """ na mesma linha.