Estilo de Código em Python – Como melhorar seu código com PEP8

Neste artigo, entenda como seguir um estilo de código para escrever códigos mais elegantes e legíveis.

Para um programador experiente, é fácil perceber quem está começando na programação. Basta ler os códigos que a pessoa escreveu.

Embora um programador júnior possa escrever códigos que funcionem perfeitamente, o que o diferencia de um programador avançado não é o conteúdo do que ele faz, mas sim a forma. Para ser considerado um programador avançado, é necessário escrever códigos elegantes, o que em programação equivale a legibilidade. Quanto mais simples for de entender o que o código faz, mais elegante ele será. 

Mas como se faz para tornar um código legível?

É isso que pretendemos explorar neste artigo com a ajuda dos guias de estilo de Python.

Estilo de código: por que escrever códigos legíveis?

Um código é muito mais frequentemente lido do escrito, e essa é a realidade nas grandes empresas e em grandes projetos compartilhados. Se você começar hoje a trabalhar em uma empresa de desenvolvimento de software, perceberá que grande parte do seu tempo inicial será dedicado à leitura de códigos e à tentativa de compreendê-los. Essa realidade é inevitável. Portanto, escrever de uma forma compreensível é fundamental. Sua equipe ganha eficiência e você poderá passar o seu tempo fazendo o que gosta – codar – e não explicando seus códigos para os outros.

O primeiro fundamento para escrever códigos legíveis é a consistência. O próprio Guido Van Rossum, criador do Python, fala o seguinte: “A consistência com o guia de estilo (o PEP8) é importante. A consistência dentro de um projeto é mais importante. A consistência dentro de um módulo ou função é o mais importante”. O que ele quer dizer com isso?

Ele está dizendo para começarmos pequeno, mas de forma consistente. Primeiro, devemos nos preocupar em manter um mesmo estilo dentro das nossas funções e módulos. Depois, nos preocupamos se nosso projeto como um todo compartilha de um mesmo estilo. Por último, nos preocupamos se nosso estilo está alinhado com as boas práticas, no caso, o PEP8.

Portanto, se um projeto já existe e tem um guia de estilo próprio, é melhor continuar escrevendo no mesmo estilo, a fim de não quebrar a compatibilidade em relação ao que já foi feito. Agora, se você está começando um novo projeto agora, recomendo que utilize o PEP8.

O que é o PEP8?

As PEPs (Python Enhancement Proposals) são sugestões de melhoria da linguagem Python propostas pela comunidade. A maior parte é referente a melhorias de eficiência ou de novas funcionalidades, mas algumas (como a PEP8) são sobre padronizações ou até sobre a filosofia por trás do Python (como a PEP20).

A PEP8 é, portanto, o guia de estilo para os programadores de Python. Ela define algumas padronizações importantes e você pode conferi-la na íntegra aqui.

A partir de agora, vamos tentar mostrar, com exemplos, as principais sugestões de estilo da PEP8. No final, adicionamos mais algumas dicas de organização de código.

A PEP8 com exemplos

Tamanho máximo de linhas

O tamanho máximo permitido pela convenção é de 79 caracteres, e esse valor não foi escolhido aleatoriamente. Ele permite que um programador abra duas abas com códigos em uma mesma tela e não sofra com problemas de visualização.

Para permitir isso, podemos utilizar a barra invertida para quebrar a linha.

with open('/path/to/some/file/you/want/to/read') as file_1, \
        open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

Linhas em branco

Devemos deixar duas linhas em branco antes de uma função. Métodos definidos dentro de uma classe devem ter uma linha em branco acima. De resto, evite utilizar linhas em branco.

Importações

Sempre devem ficar em linhas separadas.

Correto:

import os
import sys

Errado:

import os, sys

A não ser que estejam sendo importados do mesmo local.

Correto:

from subprocess import Popen, PIPE

E as importações devem estar agrupados na seguinte ordem:

1. Importações das bibliotecas-padrão de Python
2. Importações das bibliotecas de terceiros
3. Importações da aplicação local

import os
import sys

import pandas as pd
import numpy as np

from projeto import MinhaClasse

Espaços em branco

A regra aqui é não utilizar espaços desnecessários. Use espaço após vírgulas e dois-pontos.

Correto:

spam(ham[1], {eggs: 2})

Errado:

spam( ham[ 1 ], { eggs: 2 } )

Em expressões matemáticas, utilize espaços em operações de menor prioridade e mantenha as de prioridade maior juntas.

Correto:

i = i + 1
submitted += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)

Errado:

i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)

Também não use espaços em funções na hora de definir um valor padrão.

Correto:

def complex(real, imag=0.0):
    return magic(r=real, i=imag)

Errado:

def complex(real, imag = 0.0):
    return magic(r = real, i = imag)

Comentários

A primeira regra aqui é manter seus comentários atualizados.

Comentários que contradizem as funcionalidades do seu código são piores do que simplesmente não ter comentários, e isso ocorre bastante. Mudamos o funcionamento de uma função, por exemplo, e esquecemos de mudar os comentários explicativos. Isso gera uma confusão e dor de cabeça para a equipe. Então, se não estiver conseguindo manter os comentários atualizados, melhor removê-los.

A PEP8 reforça também a importância de escrevermos nossos comentários em inglês, pois é a língua universal da programação. Se você ainda não sabe inglês, sugiro fortemente que aprenda. A falta de proficiência nessa língua vai limitar suas possibilidades como programador, tanto no seu desenvolvimento quanto nas oportunidades de trabalhar em grandes projetos.

Comentários em bloco devem manter a mesma indentação do código e, para a separação de parágrafos, devemos adicionar uma linha em branco com #.

Comentários na linha são desencorajados.

x = x + 1  # não é encorajado comentar aqui, somente quando necessário

Por último, não devemos comentar coisas óbvias.

# Calcula x
def calcula_x():
   pass

Esse comentário não adiciona informação, então não deve ser escrito.

Convenção de nomes

Esse é o erro que mais evidencia a falta de experiência de um programador.

Tanto variáveis quanto funções e classes seguem um padrão de como formar seus nomes. Primeiro, vamos conhecer os tipos comuns de estilos para nomes utilizados:

• minusculo
• minusculo_com_underline (também conhecida como snake_case)
• MAIUSCULO
• MAIUSCULO_COM_UNDERLINE
• IniciaisMaiusculas (também conhecida como CamelCase)
• minusculoMaiusculo (difere da anterior na letra inicial, que é minúscula)

Nome de Variáveis e Funções

Deve seguir o padrão de minusculo_com_underline.

minha_variavel = 1
def minha_funcao():
    pass

Nome de Constantes

Segue o padrão do MAIUSCULO_COM_UNDERLINE.

PI = 3.14
VELOCIDADE_DA_LUZ = 300000

Nomes de Classes

Deve ser usada a convenção de IniciaisMaiusculas:

class MinhaClasse():
    def __init__():
        pass

Nome de Pacotes e Módulos

Devem ter um nome curto, todo em minúsculo, e o uso de underline é desencorajado.

Recomendações finais da PEP8

Comparações com None sempre devem ser feitas com is.

Correto:

if foo is None:
    pass

Errado:

if foo == None:
    pass

E a negação deve ser escrita junta.

Correto:

if foo is not None:
    pass

Errado:

if not foo is None:
    pass

Para criar uma função com nome, use sempre a palavra-chave def em vez de usar uma expressão lambda:

Correto:

def f(x):
    return 2 * x

Errado:

f = lambda x: 2 * x

Seja consistente nos retornos das funções. Ou todas as condições possuem retorno, ou nenhuma deve possuir.

Correto:

def foo(x):
    if x >= 0:
        return math.sqrt(x)
    else:
        return None
def bar(x):
    if x < 0:
        return None
    return math.sqrt(x)

Errado:

def foo(x):
    if x >= 0:
        return math.sqrt(x)
def bar(x):
    if x < 0:
        return
    return math.sqrt(x)

Para fazer comparações com início ou final de palavras, utilize os métodos startswith e endswith no lugar de slices.

Correto:

if foo.startswith('bar'):
    pass

Errado:

if foo[:3] == 'bar':
    pass

Em comparações de tipo de objetos, utilize a função isinstance() no lugar da função type().

Correto:

if isinstance(obj, int):
    pass

Errado:

if type(obj) is type(1):
    pass

Não compare valores booleanos com True ou False.

greeting = True

Correto:

if greeting:
    pass

# Errado:

if greeting == True:
    pass

# Mais errado ainda:

if greeting is True:
    pass

Recomendações finais

Todas as técnicas do PEP8 são ótimas, mas o que garante a legibilidade de um código não são técnicas em si, mas nossa capacidade de pensar como um programador. Por isso, a última dica todo bom programador com certeza aplica: nomeie bem suas variáveis.

Um bom programa é aquele que nem precisa de comentários, pois as variáveis e funções estão tão bem nomeadas e o código tão bem estruturado, que o entendimento fica intuitivo.

Primeiro, garanta que seja compreensível o que suas variáveis e funções fazem:

Correto:

numero_de_funcionarios = 20

Errado:

nf = 20

Tente ser específico, mas não tanto para não criar nomes muito grandes:

Bom:

def load_categories():
    pass

Melhor:

def load_categories_from_cache():
    pass

Utilize os argumentos da função para melhorar a legibilidade.

Bom:

list_item_to_marketplace(marketplace, item)

Melhor:

list_item_to(marketplace, item)

O exercício de tornar um código legível é um grande exercício de desenvolvimento humano. Para sermos bons nisso, devemos ser empáticos, nos colocarmos no lugar dos nossos colegas e pensar como eles pensam.

É preciso ter uma vontade profunda de facilitar o trabalho dos outros e, se carregarmos isso conosco, com certeza nosso código sairá mais legível.

Espero que essas dicas ajudem nos seus códigos. Até a próxima!