Melhores Práticas de Linting e Formatação
Uma configuração de lint e formatação de baixo atrito que captura bugs reais sem desacelerar os desenvolvedores.
Como Usar Esta Lista
- Implemente em ordem: formatador, linter, pre-commit, CI
- Ajuste os ignorados por diretório apenas com razões documentadas
- Revise o conjunto de regras trimestralmente ao atualizar o ruff
A - Escolhas de Ferramentas
- Use ruff para lint e formatação. Uma ferramenta, um arquivo de configuração, execuções em menos de um segundo.
- Configure em
pyproject.toml. Sem arquivos.flake8,setup.cfgou.isort.cfgespalhados. - Defina
target-version = "py314". As regras correspondem à sua versão do Python. - Adicione mypy ou pyright para verificação de tipos. O ruff captura o estilo; os tipos capturam erros de lógica.
B - Seleção de Regras
- Comece com E, F, I, UP, B, SIM. Adicione segurança (S) para aplicativos web e CLIs.
- Ignore E501. Deixe o formatador lidar com o comprimento da linha.
- Ignorados por arquivo para testes e migrações.
tests/**permite assert;migrations/**excluído. - Não use
select = ["ALL"]no primeiro dia. Adicione regras incrementalmente para evitar fadiga de alertas.
C - Fluxo de Trabalho do Desenvolvedor
- Formate ao salvar no editor. Faça commit de
.vscode/settings.jsonpara a equipe. - Instale hooks de pre-commit.
pre-commit installnas etapas de bootstrap do README. - Execute
ruff check --fixantes de enviar. Captura o que o pre-commit perdeu. - Nunca debata formatação em revisão de código. O formatador decide.
D - Aplicação em CI
- Execute
ruff check .eruff format --check .na CI. Ambos são verificações obrigatórias. - Fixe a versão do ruff no lockfile e no
revdo pre-commit. Local e CI permanecem sincronizados. - Use mypy/pyright como uma verificação de PR obrigatória. Não
continue-on-error. - Cacheie artefatos de lint.
.ruff_cache,.mypy_cachecom chave no lockfile.
E - Cultura da Equipe
- Todo
noqaetype: ignoreprecisa de um comentário. Explica por que a regra está suprimida. - Corrija violações de lint no arquivo que você está modificando. Regra do escoteiro reduz o backlog.
- Agende sprints de limpeza de backlog de lint. Não deixe os ignorados se acumularem para sempre.
- Atualize o ruff trimestralmente. Novas regras frequentemente capturam bugs reais.
FAQs
Qual é a configuração mínima viável de lint?
ruff check + ruff format + CI. Adicione mypy quando a base de código tiver type hints.
Como migro do flake8?
Mapeie plugins do flake8 para códigos de regra do ruff. Habilite conjuntos equivalentes. Remova o flake8 da CI.
Devo fazer lint em código gerado automaticamente?
Exclua-o. Adicione caminhos a exclude na configuração do ruff.
Quão rigoroso deve ser o mypy?
check_untyped_defs primeiro. Mova para strict módulo por módulo.
Posso pular o pre-commit?
A CI ainda deve executar as mesmas verificações. O pre-commit economiza viagens de ida e volta na CI.
Como lidar com dívida de lint legado?
Habilite regras como avisos primeiro. Corrija por módulo. Mude para erros quando estiver limpo.
Black ou ruff format?
ruff format para novos projetos. Saída equivalente, execução mais rápida.
Notebooks devem ser lintados?
Sim, com ruff format notebook.ipynb. Exclua células de saída se forem barulhentas.
Como fazer lint em um monorepo?
Um pyproject.toml na raiz com caminhos src, ou configurações por pacote com extend.
E o lint de segurança?
Habilite as regras S (bandit) para qualquer código que manipule entrada do usuário, segredos ou SQL.
Relacionado
- Configuração do Ruff - começando
- Regras Essenciais de Lint - recomendações de regras
- Hooks de pre-commit - automação local
- Linting em CI/CD - portões de pipeline
Versões das pilhas: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.