“Convenções de código” são uma faca de dois gumes… O lado bom é que você tem um código “padronizado”, limpo, legível e que poderá integrar com ferramentas externas para gerar documentação, versionamento, análise de qualidade, etc. O lado ruim é que é uma verdadeira “decoreba”… “mais trabalho” que irá exigir um guia de referências rápidas ao lado.
Em Python, uma linguagem que te obriga a indentar código, as convenções de código são objetivas e diretas. Já enfatizei no post “Pense como um Pythonista” que não programa-se em Python como em outras linguagens… o mesmo vale para as suas convenções.
Como não tenho o objetivo de reproduzir na íntegra as convenções de código do Python (pretendo somente salientar de forma direta os principais artefatos), caso você queira se aprofundar mais, leia na íntegra o “style guide for Python code” direto da documentação oficial do Python.
Espaçamentos:
- 4 espaços para indentações (somente espaços, sem tabulações)
- 1 linha em branco entre funções
- 2 linhas em branco entre classes
- adicione 1 espaço em branco depois de ‘,’ (vírgulas) em listas, tuplas, argumentos de métodos/funções e dicionários, e depois de ‘:’ (dois pontos). Mas nunca antes
- Use espaços em atribuições e comparações, exceto na lista de argumentos de métodos/funções
- Em parênteses, listas de argumentos e Docstring, não use espaços após a abertura e antes do final do bloco (ex.: (1, 2, 3) e não ( 1, 2, 3 ))
Nomes:
- desse_modo para funções, métodos e atributos
- desse_modo ou DESSE_MODO para constantes (particularmente, recomendo a segunda opção)
- DesseModo para classes
- desseModo só em casos extremamente necessários (alguns módulos mais antigos, por exemplo)
- Atributos: interface, _internal, __private (evite usar a última forma, lembre-se: Não é que se faz em Java que deve-se fazer em Python!)
Linhas longas, continuações (atenção a isso, Python funciona por indentações… lembra?!):
- Escreva em no máximo 80 colunas por linha
- Quebre blocos dentro de parênteses em linhas
- Se o caso acima não se aplica, utilize ” (barra)
Strings longas:
- Você pode quebrar uma string grande em pequenas strings, utilizando parênteses para concatená-las
- Utilize ”’ (três apóstrofos ou aspas dulpas) para criar strings de múltiplas linhas
Composição:
- Embora Python possa resolver alguns problemas em 1 linha de código, evite isso!
Comentários:
- Use Docstrings para dizer como usar o código
- Use Comentários para dizer como o código funciona
- Para bugs utilize: # !!! BUG: Isto e um bug
- Para reparos utilize: # !!! FIX: Conserte-me
- Para dúvidas utilize: # ??? Qual e a funcao disso?
Docstrings:
Confira o PEP 257 para mais informações.
- Uma linha: “””Este é um comentário em docstring.”””
- Múltiplas linhas:
“””Este é o ‘título’ do meu docstring.
Aqui eu descrevo como usar o recurso, talvez falando sobre os parâmetros a serem passados.
Note que antes de fechar o docstring é deixada uma linha em branco. Pura convenção, claro.
“””
Quando “em 1 linha” é vantagem:
- nome, idade = ‘joão’, 33
- Criando listas em 1 linha apenas: lista = [i for i in range(0, 100)]
Python é inteligente, aproveite:
- Testando se ‘joão’ existe na lista de trabalhadores: ‘joão’ in trabalhadores
- Pegando um valor de um dicionário, e retornando “False” caso não exista: trabalhadores.get(‘joão’, False)
- Se ‘joão’ não existir no dicionário, crie-o com o valor “True”, senão não faça nada: trabalhadores.setdefault(‘joão’, True)
- Para testar valores verdadeiro use if x: ao invés de if x == True:
- Use % em strings: “Olá %s” % (“Mundo”)g
Tradução na Íntegra
O PythonBrasil fez uma tradução do Guia de Estilos do Python que pode ser conferida aqui.
Considerações Finais
Seguir boas práticas de desenvolvimento é necessário para evitar futuras dores de cabeça. Conheço as convenções do PHP e do Java e te digo que tomei um susto e tanto no começo, principalmente se tratando de desenvolver componentes em PHP para o Joomla!.
Escolha bem o método com o qual você desenvolverá seus softwares. Sei muito bem que quase sempre a produtividade vem antes que a qualidade… mas qualidade de software nunca é demais! E com certeza se você trabalha em equipe, vai beneficiar e muito a produtividade.
Até a próxima…
