Esta sección presenta las convenciones sugeridas para la organización interna del código fuente en el proyecto SIGIC.

Estas convenciones deben utilizarse siempre que sean compatibles con el contexto técnico, y alinearse con las guías de estilo oficiales del lenguaje correspondiente.

Propósito

Establecer un modelo de estructura claro, predecible y escalable, sin imponer una única forma, permitiendo adaptaciones según el lenguaje de programación, el paradigma o la naturaleza del módulo.

Convenciones

Responsabilidad por archivo

Cada archivo dentro del proyecto debe cumplir una única función clara y estar estructurado de forma coherente. Esto permite mejorar la legibilidad, el mantenimiento y la escalabilidad del código.

• Un archivo puede contener una clase, un componente, un conjunto de funciones relacionadas o una configuración específica, pero no todo a la vez.
• Todos los archivos deben seguir una estructura lógica ordenada.
• Debe mantenerse el mismo orden y división para todos los módulos similares del proyecto.
• El orden debe ser coherente entre archivos similares, y reflejar la intención del módulo.

Encabezados informativos

Cada archivo debe incluir un encabezado que indique:

• Qué hace el archivo
• Quién lo escribió
• Fecha de creación/modificación (opcional si hay control de versiones)

Importante: Cuando se utilice un framework con estructura predefinida, se deberá seguir la guía oficial del propio framework como referencia prioritaria para organizar el código.

Estructura de un archivo

Se recomienda seguir el siguiente orden estructural dentro de cada archivo, ajustándose a la sintaxis y guías del lenguaje correspondiente:

1. Comentario de encabezado (propósito, autor, etc.)
2. Importaciones o dependencias externas
3. Constantes globales (si aplica)
4. Declaraciones de tipos, interfaces o estructuras (si aplica)
5. Funciones auxiliares (helpers)
6. Declaración de clase principal o función principal
7. Código de ejecución (si aplica)
8. Exportación / exposición de elementos (si aplica)

Organización a nivel proyecto

Además de la estructura dentro de cada archivo, se recomienda mantener una estructura de carpetas clara y modular en todo el repositorio.

sigic/
│
├── components/          → Interfaces, elementos visuales (si aplica)
├── services/            → Funciones de negocio o lógica de procesos
├── utils/               → Funciones auxiliares, validadores, parsers
├── models/              → Entidades, estructuras o tipos de datos
├── api/                 → Endpoints, integraciones externas
├── config/              → Configuración general, constantes, rutas
├── tests/               → Archivos de pruebas
└── docs/                → Documentación técnica

Importante: En caso de que se implemente un framework que incluya una estructura recomendada de carpetas y archivos, se deberá priorizar lo establecido en su guía oficial.

Dicha estructura podrá adoptarse total o parcialmente, siempre que preserve los principios de claridad, modularidad y responsabilidad única definidos en el presente estándar.

Cada carpeta debe seguir el mismo principio: una sola responsabilidad y archivos bien estructurados dentro.

Errores comunes

Situación	Por qué se debe evitar
Archivos con múltiples clases sin relación	Genera confusión sobre la función del archivo
Código de lógica mezclado con presentación	Dificulta el mantenimiento y la realización de pruebas
Código no modular o repetido	Aumenta la probabilidad de errores y complica el desarrollo
Código de prueba dentro de módulos productivos	Puede afectar la calidad y seguridad al desplegar el sistema

Ejemplos

Ejemplo de estructura comentada (pseudo-código)

// saludoUsuario.js
// Imprime un saludo personalizado en consola.
// Autor: Equipo de desarrollo
// Fecha: 2025-05-02

// 2. Importaciones
import readline from 'readline';

// 3. Constantes globales
const GREETING_BASE = 'Hello';

// 4. Tipos / estructuras (No aplica)

// 5. Función auxiliar
function generateGreeting(name) {
  return `${GREETING_BASE}, ${name}!`;
}

// 6. Función principal
function greetUser(name) {
  console.log(generateGreeting(name));
}

// 7. Código de ejecución
const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

rl.question('¿Cuál es tu nombre? ', (name) => {
  greetUser(name);
  rl.close();
});

// 8. Exportación (si aplica)
export { greetUser };

Aplicación conforme al lenguaje

Estas convenciones se ofrecen como modelo estructural base y pueden ajustarse conforme a:

• El lenguaje de programación que se implemente
• El estilo arquitectónico del módulo (por ejemplo, funcional y orientado a objetos)
• La guía base  de estilo del lenguaje que se proporciona en la sección Guías oficiales de estilo.

En todos los casos, debe mantenerse el orden lógico, la claridad estructural y el principio de responsabilidad única. Nota: En caso de que se adopte un framework que defina una estructura propia de archivos y componentes, se deberá dar prioridad a su guía oficial, siempre que dicha estructura mantenga la coherencia con los principios generales establecidos en este estándar.