QuartupDevDoc

Documentación de la Norma de Nomenclatura de Campos de las tablas de Quartup

---

0. Antecedentes y Justificación

Históricamente, las aplicaciones desarrolladas en Quartup utilizaban una nomenclatura de campos genérica en las tablas de la base de datos (por ejemplo, status). Este enfoque, aunque sencillo, provocaba colisiones de nombres entre campos de tablas distintas. En entornos complejos con cientos de tablas interrelacionadas, esto se convertía en un obstáculo significativo, ya que dificultaba enormemente la localización precisa de un campo determinado y sus usos.

Para resolver estos inconvenientes, se implementó un sistema que mejoraba la trazabilidad de campos utilizando el nombre completo de la tabla como prefijo para cada campo (por ejemplo, cialdocopri_status).

---

1. Principio General

La nomenclatura de los campos de las tablas SQL se regirá por la siguiente norma: se utilizará el nombre completo de la tabla como prefijo para los campos propios, mientras que los campos que actúen como claves foráneas (Foreign Keys) conservarán la misma nomenclatura que tienen en su tabla de origen. Este método garantiza una identificación única y clara del origen de cada dato en las estructuras de la aplicación, manteniendo una homogeneidad en la nomenclatura.

---

2. Formato del Nombre del Campo

El formato general para la nomenclatura de los campos será:

• Campos propios de la tabla: [nombre_tabla]_[nombre_campo]
• Campos clave foránea (Foreign Key): [nombre_tabla_origen]_[nombre_campo]

Ejemplos:

• Tabla: apirol

  • Campo propio: id
  • Nombre de Campo Resultante: apirol_id

• Tabla: apiend

  • Campo propio: descripcion
  • Nombre de Campo Resultante: apiend_descripcion

• Tabla: apirolend (tabla de relación)

  • Campo clave foránea (origen apirol): apirol_id
  • Nombre de Campo Resultante: apirol_id

---

3. Normas para el nombre_campo (campos propios de la tabla)

El nombre_campo debe ser descriptivo, conciso y semántico. Se deben evitar redundancias y priorizar nombres que clarifiquen la función del dato.

• Evitar redundancia: Si el prefijo de la tabla ya indica el contexto (por ejemplo, apirol_), no es necesario incluir la palabra "rol" nuevamente en el nombre del campo, a menos que sea crucial para evitar ambigüedades (ej., apirol_nombre_rol si existiera también apirol_nombre_usuario).
• Idioma: Se utilizará principalmente el castellano para las palabras básicas, salvo en casos muy normalizados a nivel estándar como id o similares.
• Coherencia: Se debe usar siempre la misma forma para campos comunes (por ejemplo, id, nombre, descripcion, fecha_creacion).
• Guiones bajos (_): Se emplearán guiones bajos para separar palabras en nombres de campos compuestos (por ejemplo, fecha_creacion).

---

4. Nomenclatura de Campos Heredados (Foreign Keys)

Cuando una tabla (ya sea de relación o de cualquier otro tipo) incluye campos que son identificadores (IDs) o claves foráneas de otras tablas, estos campos deben mantener la misma nomenclatura que tienen en su tabla de origen.

Esto es crucial para garantizar la coherencia y facilitar el rastreo de las relaciones entre las distintas entidades.

Ejemplo:

Para la tabla apirolend (que relaciona registros de apirol con apiend):

• El ID de la tabla apirol se denomina apirol_id.
• El ID de la tabla apiend se denomina apiend_id.

Por lo tanto, los campos en la tabla apirolend que hacen referencia a estos IDs se denominarán exactamente igual:

• apirol_id
• apiend_id

Resultado importante: No se debe anteponer el prefijo de la tabla apirolend a estos campos heredados, ya que su propósito es identificar el origen original del ID.

---

5. Beneficios de esta Norma

• Alta Trazabilidad en PHP: Los arrays asociativos en PHP tendrán claves únicas y descriptivas (como apirol_id, apiend_descripcion), lo que simplifica enormemente la identificación del origen de los datos, incluso para IDs heredados, eliminando ambigüedades.
• Claridad Directa: Esta convención elimina la necesidad de memorizar o consultar acrónimos, haciendo que el nombre del campo sea directamente comprensible para cualquier desarrollador.
• Consistencia y Uniformidad: Establece una norma clara y sencilla que promueve la uniformidad en la nomenclatura de los campos en toda la base de datos.
• Facilita el Desarrollo: Simplifica la lectura y escritura de código al interactuar con los datos extraídos de la base de datos.

---

6. Consideraciones Adicionales

• Impacto en la Longitud: Si bien esta norma mejora significativamente la claridad y la trazabilidad, es importante ser consciente de que los nombres de tablas largas resultarán en nombres de campo igualmente extensos. Este es un compromiso necesario para lograr una trazabilidad completa y sin ambigüedades.
• Transición: En el caso de tablas existentes con nomenclaturas diferentes, se recomienda considerar un plan de migración gradual o el uso de alias en las consultas SQL para los campos afectados, permitiendo que la aplicación PHP se adapte sin requerir cambios drásticos en la base de datos subyacente.