Esta sección presenta la recomendación de incorporar herramientas de análisis automático de código (linters) como parte de las buenas prácticas para el desarrollo de software dentro del proyecto SIGIC.
Estas herramientas permiten validar de forma consistente aspectos de estilo, legibilidad y organización del código fuente, según los lineamientos definidos en este estándar.
Propósito
Establecer una práctica recomendada para el uso de linters como apoyo técnico en la escritura de código fuente. Su incorporación permite:
- Detectar errores de formato, convenciones y estilo antes de la ejecución o revisión manual.
- Automatizar parte del control de calidad del código.
- Aumentar la consistencia del código entre diferentes desarrolladores y módulos.
- Complementar los lineamientos definidos en este documento con herramientas que faciliten su cumplimiento.
Convenciones
- El uso de linters es recomendable en todos los módulos del proyecto que utilicen lenguajes con soporte maduro para esta herramienta.
- Las configuraciones del linter deben mantenerse dentro del repositorio (
.eslintrc,.pylintrc, etc.) y estar disponibles para todo el equipo. - Las reglas definidas en la configuración del linter deben estar alineadas con las guías de estilo oficiales del lenguaje y los lineamientos del presente estándar.
- Las advertencias emitidas por los linters deben considerarse indicadores de mejora. El código con errores reportados por el linter no debe incorporarse sin revisión o justificación.
- No se deben desactivar reglas sin documentar la razón técnica específica en el código o en la configuración.
Ejemplos
Tabla de Linters recomendados por lenguaje
| Lenguaje | Linter recomendado | Comando de uso básico | Configuración habitual |
|---|---|---|---|
| JavaScript | ESLint | npx eslint |
.eslintrc.json |
| TypeScript | ESLint con TS parser | npx eslint archivo.ts |
.eslintrc.js, tsconfig.json
|
| Python | Flake8 / Pylint | flake8 archivo.py |
.flake8, .pylintrc
|
| Java | Checkstyle | checkstyle -c config.xml archivo |
checkstyle.xml |
| Bash | ShellCheck | shellcheck script.sh |
No requiere configuración |
| Markdown | markdownlint | npx markdownlint archivo.md |
.markdownlint.json |
Errores comunes
| Situación | Por qué se debe evitar |
|---|---|
| Código con errores de linter | Incumple las convenciones básicas del estándar |
| Desactivar reglas sin justificación | Genera inconsistencias y disminuye la confiabilidad del análisis |
| Ignorar advertencias del linter | Puede ocultar errores reales o decisiones de diseño incorrectas |
| No ejecutar linters antes del merge | Aumenta la carga de trabajo en revisión y riesgos en la rama principal |
Adaptación conforme al lenguaje
Los linters recomendados deberán adaptarse al lenguaje de programación de cada módulo. Para ello:
- Se debe utilizar la herramienta de linting reconocida por la comunidad del lenguaje.
- La configuración del linter debe reflejar las convenciones semánticas y de formato definidas en este estándar.
- En caso de conflicto entre una regla del linter y una convención establecida en este documento, deberá evaluarse el impacto técnico y ajustarse la configuración del linter si es necesario.
Integración sugerida
El uso del linter puede integrarse de forma progresiva en el flujo de desarrollo:
- Durante el desarrollo local, como verificación previa a confirmaciones (pre-commit).
- Durante las revisiones de código, como paso adicional de control de calidad.
- En pipelines de integración continua, para verificar automáticamente cada entrega de código.