Documente Academic
Documente Profesional
Documente Cultură
Tabs ou espaos?
Nunca misture tabs e espaos.
Para indentao, use 4 espaos.
Para projetos mais antigos que voc no queira bagunar, use uma tab, que equivalente a 8 espaos.
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
1/12
7/12/2014
A indentao mais popular no Python so os espaos. A segunda mais popular so as tabs. Cdigo que
usa as duas indentaes deve ser convertido para espaos apenas. Quando invocado com a opo -t, o
interpretador mostra avisos com uso de tabs e espaos no mesmo cdigo. Quando invocado com -tt,
os avisos se tornam erros. Essas opes so altamente recomendadas.
Para novos projetos, use espaos. H vrios editores com ferramentas para facilitar isso.
Tamanho da linha
Limite todas as linhas a 79 caracteres.
Ainda h muitos dispositivos que so limitados a 80 caracteres; mais, limitando o tamanho a 80
caracteres possibilita vrias janelas lado-a-lado. O wrapping nesses dispositivos atrapalha a
visualizao do cdigo. Portanto, por favor, limite todas as linhas a 79 caracteres. Para longos blocos
de texto (docstrings ou comentrios), limitar a 72 caracteres recomendado.
A melhor maneira de acondicionar linhas longas a continuao implcita entre parnteses, colchetes e
chaves. Se for necessrio, voc pode colocar parnteses em volta da expresso, mas h casos onde a
barra invertida (\) melhor. E certifique-se de uma indentao correta na linha seguinte. O melhor
lugar para quebra de linha em um operador binrio depois, no antes dele. Exemplo:
# Visualizado melhor com fonte monoespaada
class Rectangle(Blob):
def __init__(self, width, height,
color='black', emphasis=None, highlight=0):
if width == 0 and height == 0 and \
color == 'red' and emphasis == 'strong' or \
highlight > 100:
raise ValueError("sorry, you lose")
if width == 0 and height == 0 and (color == 'red' or
emphasis is None):
raise ValueError("I don't think so -- values are %s, %s" %
(width, height))
Blob.__init__(self, width, height,
color, emphasis, highlight)
Linhas em branco
Separe funes de nvel superior e definies de classe, com duas linhas em branco;
Definies de mtodo dentro de uma classe so separadas por uma linha em branco;
Linhas em branco extras podem ser utilizados (com moderao) para separar grupos de funes.
As linhas em branco podem ser omitidas entre um grupo de one-liners relacionado (por
exemplo, um conjunto de implementaes dummy);
Use linhas em branco em funes, com moderao, para indicar sees lgicas;
Python aceita o Ctrl-L (i.e. ^ L) for feed espao em branco e muitas ferramentas tratam esses
caracteres como separadores de pgina, assim voc pode us-los para separar pginas das sees
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
2/12
7/12/2014
Codificao e importaes
Codificao
Cdigo do Python deve sempre utilizar codificao ASCII ou Latin-1 (ISO-8859-1). Para Python 3.0 e
mais novos, UTF-8 prefervel ao Latin-1, consulte a PEP 3120.
Arquivos usando ASCII (ou UTF-8, para Python 3) no devem ter um encoding cookie. Latin-1 (ou
UTF-8) deve ser utilizado apenas quando um comentrio ou docstring precisa mencionar um nome de
autor que requer Latin-1, caso contrrio, prefervel usar escapes \x, \u ou \U como forma de incluir
dados no-ASCII em strings.
Para Python 3.0 e alm, a poltica a seguir deve ser usada na biblioteca padro (ver PEP 3131): Toda a
biblioteca padro deve usar somente identificadores ASCII, e deve usar palavras em Ingls, sempre
que possvel (em muitos casos, abreviaturas e termos tcnicos so usados que no so em Ingls).
Alm disso, strings e comentrios devem ser em ASCII. As nicas excees so:
casos de teste testando os recursos no-ASCII;
os nomes dos autores. Autores cujos nomes no esto baseadas na alfabeto latino deve fornecer
uma transliterao latina de seus nomes.
Projetos de cdigo aberto com uma audincia global so incentivados a adotar uma poltica similar.
Importaes
Importaes devem estar em linhas separadas:
Sim:
import os
import sys
No: import os, sys
Mas possvel usar: from subprocess import Popen, PIPE
Importaes ficam sempre no comeo do arquivo, aps os comentrios e a docstring de mdulo, e
antes da declarao das constantes e globais.
Importaes devem estar na seguinte ordem:
1. da biblioteca padro
2. de terceiros
3. locais, da aplicao
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
3/12
7/12/2014
Espaos em branco
Evite espaos em branco nas seguintes situaes:
Imediatamente dentro de parnteses, colchetes e chaves.
Sim: spam(ham[1], {eggs: 2})
No: spam( ham[ 1 ], { eggs: 2 } )
Imediatamente antes de vrgula, ponto-e-vrgula e dois-pontos:
Sim: if x == 4: print x, y; x, y = y, x
No: if x == 4 : print x , y ; x , y = y , x
Imediatamente antes do parntese de abertura da lista de argumentos de uma funo:
Sim: spam(1)
No: spam (1)
Imediatamente antes do colchete de ndices/fatias:
Sim: dict['key'] = list[index]
No: dict ['key'] = list [index]
Mais de um espao em volta de um operador para alinhar com os outros.
Sim:
x = 1
y = 2
long_variable = 3
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
4/12
7/12/2014
No:
x
= 1
y
= 2
long_variable = 3
Outras recomendaes:
Sempre coloque espaos em volta de operadores
No use espaos em volta do '=' quando uma palavra-chave de um argumento ou um valor
padro para um parmetro.
Sim:
def complex(real, imag=0.0):
return magic(r=real, i=imag)
No:
def complex(real, imag = 0.0):
return magic(r = real, i = imag)
Preferivelmente no:
if foo == 'blah': do_blah_thing()
do_one(); do_two(); do_three()
Definitivamente no:
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
5/12
7/12/2014
Comentrios e docstrings
Comentrios
Comentrios contraditrios so piores que a falta de comentrios. Sempre tenha como prioridade
atualizar os comentrios quando o cdigo muda.
Comentrios devem ser oraes completas. Se o comentrio uma frase ou orao, sua primeira letra
deve ser maiscula, a no ser que seja um identificador que comece com minscula (nunca altere a
caixa dos identificadores).
Comentrios de bloco normalmente consistem em um ou mais pargrafos com oraes completas.
Voc deve usar dois espaos aps o fim de uma orao.
Programadores de pases no anglfonos devem escrever os comentrios em ingls, a no ser que
tenham 120% de certeza que seu cdigo nunca vai ser lido por pessoas que no falam sua lngua.
Um comentrio na mesma linha de um statement (inline) deve ter ao menos dois espaos de distncia
do statement e deve comear com um '#', um espao e o texto.
Comentrios inline so desnecessrios e, de fato, distrativos quando mostram o bvio. No faa isso:
x = x + 1 # Incrementa x
Mas, s vezes, isso til:
x = x + 1 # Compensar para fronteira
Docstrings
Convenes para escrever docstrings esto na PEP 257.
Escreva docstrings para todos os mdulos, funes, classes e mtodos pblicos. Elas no so
necessrias para mtodos no pblicos, mas voc deve ter um comentrio que descreve o que o mtodo
faz. Este comentrio deve aparecer logo aps o statement def.
A PEP 257 descreve como escrever docstrings. Note que o mais importante que o """ que terminam
uma docstring de mltiplas linhas deve ter sua prpria linha, de preferncia, precedida por uma linha
em branco. Exemplo:
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
6/12
7/12/2014
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
Para docstrings de uma linha, pode-se colocar o """ na mesma linha.
Escriturao de verso
Se voc precisa usar o Subversion, CVS, ou RCS crud em seu arquivo de origem, faa como no
exemplo abaixo.
__version__ = "$Revision: 68852 $"
Estas linhas devem ser includas aps a docstring do mdulo, antes de qualquer outro cdigo,
separadas por uma linha em branco acima e abaixo.
Convenes de nomenclatura
As convenes de nomenclatura da biblioteca Python so um pouco confusas, por isso, nunca vamos
t-las completamente consistentes - no entanto, aqui esto os padres de nomenclatura recomendados.
Novos mdulos e pacotes (incluindo os de terceiros) devem ser escritos seguindo essas normas, mas
em uma biblioteca existente que tenha um estilo diferente, a consistncia interna preferida.
H uma srie de diferentes estilos de nomeao.Ela ajuda a ser capaz de reconhecer qual estilo est
sendo utilizada, independentemente do que eles so usados.
Os estilos de nomeao que se seguem so comumente observados:
b (uma letra minscula)
(uma letra maiscula)
minsculas
minsculas_com_underscores
MAISCULAS
MAISCULAS_COM_UNDERSCORES
IniciaisMaisculas (ou CapWords ou CamelCase)
NOTA: Quando usar abreviaes em CapWords, capitalizar todas as letras da sigla. Assim
HTTPServerError melhor que HttpServerError.
mixedCase (diferente de IniciaisMaisculas pela inicial minscula)
Iniciais_Maisculas_Com_Underscores (feio!)
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
7/12
7/12/2014
H tambm o estilo da utilizao de um prefixo curto para grupo de nomes relacionados. Isso no
muito usado em Python.
Por exemplo, o os.stat() retorna uma tupla cujos itens tradicionalmente tm nomes como st_mode,
st_size, st_mtime e assim por diante.
A biblioteca X11 usa uma inicial X para todas as suas funes pblicas. Em Python, este estilo
geralmente considerado desnecessrio porque atributos e nomes de mtodos so prefixados com um
objeto, e os nomes das funes so precedidas por um nome de mdulo.
_um_underscore_inicial: Indicador de uso interno. Por exemplo: "from M import *" no importa
os objetos cujo nome comea com um underscore.
um_underscore_final_: utilizado por conveno para evitar conflitos com palavras-chave
Python. Exemplo:
Tkinter.Toplevel(master, class_ = 'className')
__double_leading_underscore: Ao nomear um atributo de classe, invoca a desconfigurao do
nome (dentro da classe FooBar, __boo se torna _FooBar__boo).
__double_leading_and_trailing_underscore__: Objetos "mgicos" ou atributos que vivem em
espaos de nome controlado pelo usurio. Por exemplo: __init__, __import__ ou __file__.
Nunca invente tais nomes, apenas use-os como documentado.
Nunca use os caracteres 'l' (ele minsculo), 'O' (o maisculo), ou I, (i maisculo) como nome de uma
varivel de um caractere.
Em algumas fontes, esses caracteres so indistinguveis dos numerais um e zero. Quando tentado a
usar o 'l', use' L' em seu lugar.
Mdulos devem ter todo o nome em minsculas. Underscores podem ser usados no nome do mdulo
se ele melhora a legibilidade. Pacotes Python devem ter um nome curto, todo em minsculas, embora
nesse caso o uso de sublinhados seja desencorajado.
Uma vez que nomes de mdulos so mapeados para nomes de arquivos, e alguns sistemas de arquivos
no diferenciam maisculas de minsculas e truncam nomes longos, importante que o nome do
mdulo escolhido seja bastante curto - isto no ser um problema em Unix, mas pode ser um problema
quando o cdigo transportado para Macs mais velhos ou Windows e DOS.
Quando um mdulo de extenso escrito em C e C++ tem um mdulo em Python como
acompanhamento que fornea uma interface com mais alto nvel (por exemplo, mais orientada a
objetos), o mdulo em C/C++ comea com um underscore (_socket, por exemplo).
Quase sem exceo, os nomes de classe usam a conveno IniciaisMaisculas. Classes para uso
interno, alm disso, comeam com um underscore.
Como excees so classes, a conveno de nomes para classes se aplica aqui. No entanto, voc deve
usar o sufixo "Error" no nome de sua exceo (se a exceo um erro).
As convenes para variveis globais so as mesmas para as funes. Os mdulos que so projetados
para uso via "from M import *" devem usar o mecanismo de preveno __all__ para prevenir que
globais para uso interno sejam exportadas ou um underscore no comeo do nome.
Nomes de funes devem estar em letras minsculas, com palavras separadas por sublinhados como
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
8/12
7/12/2014
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
9/12
7/12/2014
Recomendaes de programao
O cdigo deve ser escrito de uma forma que no deixe em desvantagem outras implementaes de
Python (PyPy, Jython, IronPython, Pyrex, Psyco etc). Por exemplo, no use a implementao eficiente
do CPython para concatenao de string "a +=b" ou "a = a + b". Isto corre mais lentamente em Jython.
Em partes da biblioteca de performance sensvel, ''.join() deve ser usado.
Isto garantir que a concatenao ocorra em tempo linear entre as diferentes implementaes.
Comparaes de singletons como None devem ser sempre feitas com 'is' ou 'not', nunca com
operadores de igualdade. Alm disso, cuidado com "if x" quando voc realmente quer dizer "if x is not
None" Por exemplo, quando testar se uma varivel ou argumento no qual os padres de None foram
definidos para outro valor. O valor pode ter um outro tipo (Como um container), que pode ser falsa em
um contexto booleano.
Use excees baseadas em classes.
Excees de string em cdigo novo proibido, porque este recurso da linguagem est sendo removido
no Python 2.6.
Mdulos ou pacotes devem definir sua prpria classe base de exceo para seu domnio especfico,
que deve ser uma subclasse de Exception. Sempre inclua uma docstring. Por exemplo:
class MessageError(Exception):
"""Base class for errors in the email package."""
Ao levantar uma exceo, use "raise ValueError('message')" no lugar da forma mais antiga "raise
ValueError, 'message'".
A forma com parnteses preferida porque quando os argumentos so longos e incluem a formatao
de string, voc no precisa usar os caracteres de continuao de linha. A forma antiga ser removido
no Python 3000.
Mencionar excees especficas em try: ... except:.
Por exemplo, use:
try:
import platform_specific_module
except ImportError:
platform_specific_module = None
Uma clusula except: nua pega SystemExit e KeyboardInterrupt Ctrl-C, e pode mascarar outros
problemas. Se voc quiser pegar todas as excees que sinalizam erros no programa use "except
Exception:".
Uma boa regra limitar a utilizao de clusulas except nuas para dois casos:
1) Se o manipulador de exceo ir imprimir ou logar o traceback, pelo menos, o usurio estar ciente
de que um erro ocorreu.
2) Se o cdigo precisa fazer algum trabalho de limpeza, mas depois deixa a exceo se propagar com
"raise". "try: ... finally:"
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
10/12
7/12/2014
a melhor maneira de lidar com este caso. Alm disso, para todos os try/excepts limite o try ao
mnimo cdigo necessrio.
Novamente, isto evitar o mascaramento de erros.
Sim:
try:
value = collection[key]
except KeyError:
return key_not_found(key)
else:
return handle_value(value)
No:
try:
# Too broad!
return handle_value(collection[key])
except KeyError:
# Will also catch KeyError raised by handle_value()
return key_not_found(key)
11/12
7/12/2014
if isinstance(obj, StringType) or \
isinstance(obj, UnicodeType):
Para as sequncias (strings, listas, tuplas), use o fato de que sequencias vazias so falsas.
Sim: if seq:
No: if len(seq):
No escrever literais string que dependem de espaos em branco no final. A quantidade desses espaos
visualmente indistinguvel e alguns editores (ou, mais recentemente reindent.py), vai cort-las.
No compare valores booleanos usando ==:
Sim: if greeting:
No: if greeting == True:
Pior: if greeting is True:
http://www.vivaolinux.com.br/artigo/PEP-8-Guia-de-estilo-para-codigo-Python
Voltar para o site
http://www.vivaolinux.com.br/artigos/impressora.php?codigo=11375
12/12