PEP 8 e ferramentas de estilo

O que a PEP 8 recomenda

O Python tem um guia de estilo oficial, a PEP 8, que define como o código deve se parecer para ser consistente em toda a comunidade. As regras não são caprichos: elas existem porque código é lido muito mais vezes do que é escrito, e a consistência reduz o esforço de leitura. A PEP 8 padroniza coisas como indentação de quatro espaços, nomes em minúsculas com sublinhado para funções e variáveis, nomes em CapWords para classes, espaçamento ao redor de operadores e limite de comprimento das linhas. Nada disso muda o que o código faz; muda o quanto ele é fácil de entender.

Um princípio guia toda a PEP 8: o código deve favorecer quem lê. Nomes descritivos valem mais que nomes curtos e enigmáticos. Espaçamento consistente evita que o olho tropece. A própria PEP 8 lembra que a consistência dentro de um projeto importa mais do que seguir a regra ao pé da letra em todo caso isolado. O objetivo não é obedecer por obediência, e sim que qualquer pessoa da equipe consiga ler o código de qualquer outra sem atrito.

black: o formatador que encerra a discussão

Seguir a PEP 8 na mão é trabalhoso e gera discussões intermináveis em equipe sobre onde quebrar uma linha ou quantos espaços usar. O formatador black resolve isso de um jeito radical: ele reescreve o seu código num estilo único e determinístico, sem opções para debater. Você roda o black e o arquivo sai formatado, sempre do mesmo jeito. A vantagem não é só a consistência; é acabar com o debate. Como todo mundo usa o mesmo formatador, ninguém discute estilo em revisão de código, e a energia vai para o que importa, que é a lógica.

# Antes do black: espacamento inconsistente
def somar( a,b ):
    return a+b

resultado=somar(1,2)

# Depois do black: estilo unico e previsivel
def somar(a, b):
    return a + b


resultado = somar(1, 2)

O black reescreve o código num estilo padronizado; a formatação deixa de ser assunto de discussão.

ruff: o verificador rápido de estilo e erros

Enquanto o black cuida da formatação, o ruff cuida da análise. Ele é um linter, uma ferramenta que lê o código sem executá-lo e aponta uma lista de problemas: variáveis importadas e não usadas, nomes que fogem da PEP 8, código inalcançável, comparações suspeitas e muitas outras armadilhas. O ruff ganhou o ecossistema por ser extremamente rápido e por reunir, numa ferramenta só, o trabalho de vários verificadores antigos. Rodar o ruff sobre o projeto é como ter um revisor incansável que passa os olhos em cada arquivo e sinaliza o que merece atenção.

import os          # ruff avisa: importado mas nunca usado

def processar(dados):
    total = 0
    for d in dados:
        total += d
    return totl     # ruff avisa: nome "totl" nao definido (provavel erro de digitacao)

# O ruff aponta esses problemas sem executar o codigo,
# pegando descuidos antes que virem bug.

O ruff detecta import não usado e nome inexistente sem rodar o código, pegando erros cedo.

Vale a distinção de papéis para não confundir com o módulo anterior. O black e o ruff cuidam de estilo e boas práticas do código escrito. O mypy, visto lá no começo do curso, cuida da coerência de tipos. O pytest cuida do comportamento, com testes. São quatro ferramentas complementares, e um projeto bem cuidado costuma usar todas: o black formata, o ruff aponta descuidos, o mypy confere os tipos e o pytest prova que funciona. Nenhuma substitui a outra, e juntas formam a rede de qualidade que marca o trabalho profissional.