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.

[ Hits: 58.192 ]

Por: Artur Gaspar em 20/04/2010


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.

"""

Para docstrings de uma linha, pode-se colocar o """ na mesma linha.

Página anterior     Próxima página

Páginas do artigo
   1. Introdução
   2. Tamanho da linha e linhas em branco
   3. Codificação e importações
   4. Espaços em branco
   5. Comentários e docstrings
   6. Escrituração de versão e convenções de nomenclatura
   7. Recomendações de programação
   8. PEP 20 - The Zen of Python - de Tim Peters
Outros artigos deste autor

Instalando e configurando o VirtualBox

Leitura recomendada

Python para pesquisadores: material didático

Clicador automático de Tinder com Python

Reconhecimento de placas de veículos com OpenALPR

Trabalhando com permutações em ordem lexicográfica crescente

Threads - Importância dentro de um software

  
Comentários
[1] Comentário enviado por removido em 20/04/2010 - 12:00h

Muito bom.


Contribuir com comentário