Esta sección establece las convenciones de nomenclatura para todo tipo de identificadores utilizados en el proyecto SIGIC. Estas convenciones se aplican a variables, funciones, clases, archivos, carpetas, módulos, rutas, componentes y constantes, sin importar el lenguaje de programación utilizado.

---

Propósito

Garantizar un código claro, comprensible y sostenible mediante la adopción de un vocabulario técnico común y la estandarización del significado de los nombres a través de diferentes lenguajes de programación.

---

Convenciones

Las siguientes convenciones definen la estructura lógica y el significado que debe tener cada tipo de nombre en el código. Su cumplimiento es obligatorio, independientemente del lenguaje de programación.

• Los nombres deben expresar con claridad su propósito.
  Ejemplos: userList, calculateTotalRevenue(), isSessionActive
• Deben ser específicos y contextualizados.
  Evitar nombres genéricos como data o list; preferir documentMetadataList
• El nombre debe reflejar el tipo de dato, estructura o comportamiento.
  • Booleanos → prefijos como is, has, can, should
  • Listas o colecciones → en plural
  • Funciones o métodos → verbo + objeto
  • Clases o componentes → sustantivo en singular
  • Variables simples → sustantivos descriptivos, sin incluir el tipo (a menos que el lenguaje lo exija)
• Lenguaje técnico en inglés; comentarios en español técnico.
  • Todos los identificadores del código deben escribirse en inglés técnico, siguiendo las convenciones del lenguaje de programación correspondiente.
  • Los comentarios y documentación pueden redactarse en español técnico claro, manteniendo consistencia y utilizando los nombres del código exactamente como aparecen.
  • Ejemplo:

javascript
// Se valida que userList no esté vacía antes de continuar con la operación
if (userList.length === 0) {
  return;
}

---

Tipado de Datos

El uso explícito del tipo de dato en declaraciones de variables, funciones y estructuras se recomienda como una práctica que refuerza la semántica del código y mejora su claridad. Cuando el lenguaje de programación lo permita, debe utilizarse tipado estático o anotaciones de tipo, conforme a la guía de estilo correspondiente. El tipado de datos contribuye a:

• Mejora la comprensión inmediata del propósito de un identificador.
• Previene errores en tiempo de ejecución mediante validación en tiempo de compilación o análisis estático.
• Fortalece la documentación implícita del código.
• Facilita el uso eficiente de herramientas de desarrollo (autocompletado, inspección, navegación, etc.).

Esta convención es aplicable a variables, argumentos, valores de retorno, estructuras y colecciones. Su uso debe ser coherente con el nombre del identificador y su comportamiento.

• Ejemplo:

typescript
let userName: string;
let isActive: boolean;

function calculateTotal(price: number, tax: number): number {
  return price + tax;
}

Python (con type hints):

python
def send_email(recipient: str, subject: str, body: str) -> bool:
    ...

Java:

java
public boolean isSessionActive(User user) {
    return user != null && user.isAuthenticated();
}

Uso coherente del vocabulario técnico

• Usar un único término por concepto en todo el proyecto.
  Ejemplo: si se usa report, no usar summary, document u overview para el mismo propósito.
• Evitar nombres genéricos, vacíos o crípticos:
  temp, datax, thing, var1, foo, abc123

Composición según tipo de identificador

Tipo de identificador	Convención semántica	Ejemplos
Variable simple	Sustantivo claro	userName, pageTitle
Variable booleana	Prefijo (is, has, etc.)	isLoggedIn, hasPermission
Lista o colección	Sustantivo en plural	activeUsers, pendingRequests
Función o método	Verbo + objeto	sendNotification(), logError()
Clase o componente	Sustantivo singular o compuesto	DocumentParser, UserService
Archivo o módulo	Sustantivo específico	user_profile, report_export
Ruta de API	Acción o entidad clara	/sigic/upload-file, /sigic/users

Uso del prefijo SIGIC

Se debe anteponer el prefijo sigic a identificadores clave que representan componentes centrales del sistema, especialmente aquellos compartidos en múltiples módulos o con valor global dentro de la arquitectura del proyecto.

Ejemplos:

• sigicReportService
• sigicMetadataValidator
• sigicDashboardController

Consistencias entre módulos

• Un mismo concepto debe mantener el mismo nombre en todos los archivos y módulos.
  Ejemplo: userSession (en lugar de variantes como sessionData, authToken).
• Nombres similares deben representar distinciones claras:
  rawDocumentData vs processedDocumentData
userForm vs userView

---

Errores comunes

Nombre incorrecto	Motivo de rechazo
x, var, temp	No comunican propósito
myFunction, doStuff	Nombres genéricos sin valor semántico
getData() (que borra datos)	Nombre contradictorio con la acción real
dataData, userUserList	Redundancia innecesaria
usr, pmt, dcm	Abreviaciones sin significado evidente

---

Ejemplos

Propósito	Nombre básico lógico	Java	Python	JavaScrip
Lista de usuarios activos	activeUserList	activeUserList	active_user_list	activeUserList
Estado de sesión activa	isSessionActive	isSessionActive	is_session_active	isSessionActive
Servicio de reporte SIGIC	sigicReportService	SigicReportService	SigicReportService	SigicReportService

---

Aplicación conforme al lenguaje

Las convenciones semánticas establecidas en esta sección son obligatorias y permanentes. Reflejan la lógica técnica del proyecto y no deben ser modificadas, independientemente del lenguaje o stack adoptado.

Una vez definido el lenguaje del módulo, se deberá utilizar la guía de estilo como referencia correspondiente para adaptar:

• La forma sintáctica del nombre (por ejemplo, camelCase, snake_case, PascalCase).
• Las convenciones del lenguaje que definen el uso correcto de mayúsculas y la forma de escribir palabras compuestas o separadas.

⚠️IMPORTANTE:
En caso de conflicto entre la convención sintáctica del lenguaje y la convención semántica definida en este estándar, prevalece el significado técnico del nombre. La forma se adapta al lenguaje, pero el propósito y estructura lógica deben mantenerse sin alteraciones.

---