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)

---

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.

---