Mejores Prácticas de Linting y Formateo
Una configuración de linting y formateo de baja fricción que detecta errores reales sin ralentizar a los desarrolladores.
Cómo Usar Esta Lista
- Implementar en orden: formateador, linter, pre-commit, CI
- Ajustar ignorados por directorio solo con razones documentadas
- Revisar el conjunto de reglas trimestralmente al actualizar ruff
A - Elección de Herramientas
- Usar ruff para linting y formateo. Una herramienta, un archivo de configuración, ejecuciones en menos de un segundo.
- Configurar en
pyproject.toml. Sin.flake8,setup.cfg, o.isort.cfgdispersos. - Establecer
target-version = "py314". Las reglas coinciden con tu versión de Python. - Añadir mypy o pyright para la verificación de tipos. Ruff detecta el estilo; los tipos detectan errores de lógica.
B - Selección de Reglas
- Empezar con E, F, I, UP, B, SIM. Añadir seguridad (S) para aplicaciones web y CLIs.
- Ignorar E501. Dejar que el formateador maneje la longitud de línea.
- Ignorados por archivo para tests y migraciones.
tests/**permiteassert;migrations/**excluido. - No usar
select = ["ALL"]desde el primer día. Añadir reglas incrementalmente para evitar la fatiga de alertas.
C - Flujo de Trabajo del Desarrollador
- Formatear al guardar en el editor. Confirmar
.vscode/settings.jsonpara el equipo. - Instalar hooks de pre-commit.
pre-commit installen los pasos de inicialización de README. - Ejecutar
ruff check --fixantes de hacer push. Detecta lo que pre-commit omitió. - Nunca debatir el formato en la revisión de código. El formateador decide.
D - Aplicación en CI
-
ruff check .yruff format --check .en CI. Ambas son comprobaciones requeridas. - Fijar la versión de ruff en el lockfile y en la
revde pre-commit. Local y CI se mantienen sincronizados. - mypy/pyright como una comprobación de PR requerida. No
continue-on-error. - Caché de artefactos de linting.
.ruff_cache,.mypy_cacheindexados por el lockfile.
E - Cultura de Equipo
- Cada
noqaytype: ignorenecesita un comentario. Explica por qué se suprime la regla. - Corregir violaciones de linting en el archivo que tocas. Regla del boy-scout para reducir el backlog.
- Programar sprints de limpieza del backlog de linting. No dejar que los ignorados se acumulen para siempre.
- Actualizar ruff trimestralmente. Las nuevas reglas a menudo detectan errores reales.
Preguntas Frecuentes
¿Cuál es la configuración mínima viable de linting?
ruff check + ruff format + CI. Añadir mypy cuando la base de código tenga type hints.
¿Cómo migro desde flake8?
Mapear plugins de flake8 a códigos de reglas de ruff. Habilitar conjuntos equivalentes. Eliminar flake8 de CI.
¿Debo hacer linting de código autogenerado?
Excluirlo. Añadir rutas a exclude en la configuración de ruff.
¿Qué tan estricto debe ser mypy?
check_untyped_defs primero. Mover a strict módulo por módulo.
¿Puedo saltarme pre-commit?
CI aún debe ejecutar las mismas comprobaciones. pre-commit ahorra viajes de ida y vuelta a CI.
¿Cómo manejo la deuda de linting heredada?
Habilitar reglas como advertencias primero. Corregir por módulo. Cambiar a errores cuando esté limpio.
¿Black o ruff format?
ruff format para proyectos nuevos. Salida equivalente, ejecución más rápida.
¿Deben hacerse linting de los notebooks?
Sí, con ruff format notebook.ipynb. Excluir celdas de salida si son ruidosas.
¿Cómo hacer linting de un monorepo?
Un pyproject.toml en la raíz con rutas src, o configuraciones por paquete con extend.
¿Qué hay del linting de seguridad?
Habilitar las reglas S (bandit) para cualquier código que maneje entrada de usuario, secretos o SQL.
Relacionado
- Configuración de Ruff - primeros pasos
- Reglas Esenciales de Linting - recomendaciones de reglas
- Hooks de pre-commit - automatización local
- Linting en CI/CD - puertas de enlace en el pipeline
Versiones de Stack: Esta página fue 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+, y uv 0.6+.