Esta sección presenta las buenas prácticas sugeridas para el desarrollo de código en el proyecto SIGIC. Estas prácticas complementan las convenciones formales de estilo del lenguaje en aspectos como formato, estructura, nomenclatura y documentación. Deben aplicarse siempre que sean compatibles con el lenguaje, el paradigma o el tipo de módulo, y mantenerse alineadas con las buenas prácticas definidas en la guía de estilo oficial correspondiente, establecida en la sección Guías de estilo oficiales, la cual es de uso obligatorio según este estándar.
Propósito
Establecer buenas prácticas que complementen las reglas de formato, nomenclatura, estructura y comentarios, con el fin de garantizar que el código del proyecto SIGIC sea comprensible, mantenible, escalable, seguro, eficiente, probado y coherente.
Convenciones
-
Código ordenado y confiable
Un código limpio, consistente y bien documentado es más fácil de mantener y menos propenso a errores. -
Evita la repetición innecesaria
Repetir código aumenta la probabilidad de errores y dificulta las actualizaciones o cambios futuros. -
Responsabilidad única por componente
Cada clase, módulo o función debe tener una única función clara dentro del sistema. -
Escribe para el equipo, no solo para ti
El código debe poder ser entendido por cualquier persona que lo lea, ahora o en el futuro.
Buenas Prácticas
| Recomendación | Descripción |
|---|---|
| Funciones pequeñas | Cada función debe cumplir una única tarea de forma clara y específica. |
| Validación de datos | Nunca dar por hecho que la entrada es válida; válida siempre antes de procesar. |
| Manejo explícito de errores | Los errores deben gestionarse de forma clara y visible, sin ocultarlos ni ignorarlos. |
| Evitar variables globales | Limita el alcance de las variables para evitar efectos colaterales no deseados. |
| Modularidad | Divide el código en partes independientes, reutilizables y fáciles de mantener. |
| Pruebas automáticas | Implementar pruebas unitarias o funcionales para asegurar el comportamiento esperado. |
| Código sin dejar basura | Elimina fragmentos de código no utilizados, pruebas temporales y comentarios obsoletos. |
| Flujo de trabajo en Git | Se recomienda adoptar un modelo de ramificación estructurado, como el propuesto en A successful Git branching model, para mantener un entorno colaborativo ordenado y predecible en proyectos con múltiples desarrolladores. |
Archivo README.md en cada módulo |
Todo repositorio debe incluir un archivo README.md que documente el propósito, requisitos, instalación, uso y guía para contribuir al módulo. Esto permite que otros desarrolladores comprendan, configuren y reutilicen el código sin intervención directa. |
| Guía visual para el ancho de línea | Se recomienda configurar el editor para mostrar una referencia visual que indique el ancho máximo definido en el estándar del proyecto. Esto mejora la legibilidad del código y ayuda a respetar las convenciones de formato establecidas en el equipo. |
| Herramientas para generar documentación | Se sugiere explorar extensiones o herramientas de desarrollo que automaticen la generación de documentación técnica, como bloques de comentarios o docstrings, de acuerdo al lenguaje utilizado. Por ejemplo, en Python puede utilizarse la extensión autoDocstring, que emplea el formato Google Style por defecto. Estas herramientas pueden adoptarse de forma progresiva según la tecnología y entorno de desarrollo del equipo. |
Seguridad y Robustez
- Nunca expongas contraseñas, tokens o claves en el código.
- Usa variables de entorno o archivos de configuración fuera del código fuente.
- No asumas que los datos del usuario son correctos.
- Considera errores externos (API fallida, archivo corrupto, red caída).
Pruebas y Control de Calidad
- Toda lógica importante debe tener pruebas unitarias o funcionales.
- Las pruebas deben estar en archivos separados y estructurados.
- Los nombres de pruebas deben indicar qué se está verificando.
- Todo el equipo debe poder ejecutar las pruebas.
- No se permite pasar código a producción sin pruebas básicas si el módulo lo requiere.
Responsabilidad Compartida
Las buenas prácticas no son opcionales. Todo el equipo es responsable de:
- Aplicarlas en su código.
- Reportar y corregir desviaciones en revisiones de código.
- Mejorarlas si el contexto lo justifica, pero nunca ignorarlas.
Adaptación Conforme al Lenguaje
Estas prácticas son sugeridas y se espera que sean aplicables a cualquier lenguaje o paradigma de programación. Una vez definido el stack tecnológico del proyecto SIGIC, deberán complementarse con el uso de herramientas específicas como linters, frameworks de pruebas, validadores o analizadores estáticos, entre otros. Es requisito que estas prácticas se apliquen en conjunto con las guías de estilo oficiales recomendadas en este estándar, las cuales son de uso obligatorio para todos los módulos del proyecto.