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

• 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.
• 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

Los archivos deben tener encabezados informativos

• Qué hace el archivo, quién lo escribió, fecha de creación/modificación (opcional si hay control de versiones).

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

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.