PEP 8 no Python: estilo, nomes e formatação

A PEP 8 é o guia de estilo mais conhecido para código Python. Ela reúne recomendações sobre indentação, nomes, espaçamento, imports, comprimento de linhas e organização geral. Seguir essas práticas deixa o código mais legível, consistente e fácil de manter.

O que é PEP 8?

PEP significa Python Enhancement Proposal. A PEP 8 descreve convenções de estilo para programas escritos em Python. Ela não altera o funcionamento da linguagem: o objetivo é ajudar pessoas e equipes a escrever código com uma aparência previsível.

A regra mais importante é a legibilidade. Em projetos com um padrão já estabelecido, mantenha a consistência do código existente.

Resumo das principais regras da PEP 8

1. Indentação com quatro espaços

Python usa indentação para delimitar blocos. A recomendação é usar quatro espaços por nível e não misturar tabs e espaços no mesmo projeto.

def verificar_idade(idade):
    if idade >= 18:
        return "Maior de idade"
    return "Menor de idade"

Configure o editor para inserir quatro espaços quando a tecla Tab for pressionada. Isso mantém a digitação confortável sem gravar caracteres de tabulação no arquivo.

2. Nomes de variáveis, funções, classes e constantes

• Variáveis e funções: snake_case, como calcular_total.
• Classes: PascalCase, como ContaBancaria.
• Constantes: letras maiúsculas, como TAXA_JUROS.
• Módulos: nomes curtos em minúsculas, como relatorios.py.
• Nomes internos: um underline inicial pode indicar uso interno, como _validar_dados.

TAXA_DESCONTO = 0.10


class CarrinhoDeCompras:
    def calcular_total(self, valor_produtos):
        desconto = valor_produtos * TAXA_DESCONTO
        return valor_produtos - desconto

Prefira nomes que descrevam a intenção. total_pedido comunica mais do que tp, e usuario_ativo é mais claro do que flag.

3. Comprimento de linhas

A recomendação clássica da PEP 8 é manter linhas de código em até 79 caracteres e comentários ou docstrings em até 72. Muitas equipes adotam limites diferentes com formatadores automáticos; o essencial é escolher um padrão e aplicá-lo de forma consistente.

Quando uma expressão ficar longa, prefira quebrá-la dentro de parênteses:

mensagem = (
    "Não foi possível concluir o cadastro porque "
    "alguns campos obrigatórios estão vazios."
)

resultado = (
    valor_produtos
    + valor_frete
    - valor_desconto
)

4. Espaços em operadores, vírgulas e argumentos

Use um espaço ao redor de operadores como =, +, - e ==, além de um espaço depois de vírgulas. Não coloque espaços imediatamente dentro de parênteses.

# Evite
resultado=preco*quantidade
nomes=["Ana","Bruno","Carla"]

# Prefira
resultado = preco * quantidade
nomes = ["Ana", "Bruno", "Carla"]

Em argumentos nomeados de funções, normalmente não se usam espaços ao redor do sinal de igual:

print("Relatório", end="\n\n")
conectar(host="localhost", timeout=10)

5. Organização dos imports

Coloque os imports no início do arquivo, depois da docstring do módulo. Separe-os em três grupos: biblioteca padrão, pacotes externos e módulos locais.

import json
from pathlib import Path

import requests

from meu_projeto.config import CONFIGURACOES
from meu_projeto.servicos import buscar_dados

Evite from modulo import *, pois essa forma dificulta saber de onde cada nome veio e pode causar conflitos.

6. Linhas em branco e organização do arquivo

• Separe classes e funções de nível superior com duas linhas em branco.
• Dentro de uma classe, separe métodos com uma linha em branco.
• Use linhas em branco com moderação para dividir etapas lógicas de uma função.
• Evite funções muito extensas; extraia partes com responsabilidades próprias.

7. Comparações e expressões booleanas

# Evite
if usuario_ativo == True:
    enviar_mensagem()

if resultado == None:
    registrar_erro()

# Prefira
if usuario_ativo:
    enviar_mensagem()

if resultado is None:
    registrar_erro()

Para verificar se uma coleção está vazia, você também pode usar diretamente seu valor booleano:

if not itens:
    print("A lista está vazia.")

8. Comentários e docstrings

Comentários devem explicar decisões, restrições ou motivos — não repetir literalmente o código. Para documentar módulos, classes e funções públicas, use docstrings.

def calcular_media(notas):
    """Retorna a média aritmética de uma sequência de notas."""
    if not notas:
        raise ValueError("Informe ao menos uma nota.")

    return sum(notas) / len(notas)

Veja também os guias sobre comentários em Python e docstrings em Python.

Exemplo antes e depois da PEP 8

Código difícil de ler

def calc(v,q,d=0):
 r=v*q
 if d>0:r=r-(r*d)
 return r

Código reorganizado

def calcular_total(preco, quantidade, desconto=0):
    subtotal = preco * quantidade

    if desconto > 0:
        subtotal -= subtotal * desconto

    return subtotal

Além do espaçamento, a versão reorganizada usa nomes descritivos, blocos claros e linhas em branco para separar as etapas do cálculo.

PEP 8, formatador e linter: qual é a diferença?

Esses recursos se complementam. Um formatador reduz discussões sobre aparência, enquanto um linter encontra problemas que a formatação sozinha não resolve.

pip install black ruff flake8

black .
ruff check .
flake8 .

Checklist de PEP 8

• O código usa quatro espaços por nível de indentação?
• Variáveis e funções têm nomes em snake_case?
• Classes usam PascalCase?
• Imports estão no início e separados por grupo?
• Há espaços ao redor de operadores e depois de vírgulas?
• Linhas longas foram quebradas de forma legível?
• Funções e classes estão separadas por linhas em branco?
• Comparações com None usam is ou is not?
• Comentários explicam o motivo, em vez de repetir o código?
• Um formatador ou linter está configurado no projeto?

Perguntas frequentes sobre PEP 8

A PEP 8 é obrigatória?

Não. Ela é uma convenção, não uma regra da linguagem. Porém, seguir um padrão consistente melhora a colaboração e a manutenção do projeto.

Seguir a PEP 8 melhora o desempenho?

Normalmente, não altera a velocidade do programa. O benefício principal é tornar o código mais claro, previsível e fácil de revisar.

Posso usar um limite de linha diferente de 79?

Sim. Muitas equipes adotam outro limite por causa do formatador ou das características do projeto. Documente a decisão e mantenha o mesmo padrão em todo o código.

Qual ferramenta usar para começar?

Um formatador como Black e um linter como Ruff ou Flake8 já automatizam grande parte das verificações de estilo.

Conclusão

A PEP 8 não serve apenas para deixar o código “bonito”. Ela cria uma linguagem visual comum para quem escreve e revisa Python. Comece com indentação, nomes, imports e espaçamento; depois, automatize as verificações com um formatador e um linter.