En los últimos meses, preparándome para lanzar un nuevo proyecto, me di cuenta de algo fundamental: el código no solo lo leen las máquinas, lo leemos nosotros.
Tras condensar las mejores prácticas de excelentes profesionales con los que me he cruzado en mi carrera, decidí abrir este recurso a la comunidad: OracleApex-Code-Standards.
Se trata de estándares aplicables en el mundo real para crear aplicaciones robustas, escalables y con mantenibilidad a largo plazo. En lugar de un inmenso muro de texto, he organizado todos nuestros lineamientos en prácticas tablas de referencia por área.
📐 1. Principios Generales y Convenciones de Nomenclatura
El orden global y la forma en la que nombramos nuestros objetos dicta el estándar visual del repositorio.
| Categoría | Regla / Estándar | Detalle o Práctica Recomendada |
|---|---|---|
| Formato y Alineación | Indentación de 2 espacios estrictos | No se usan tabuladores. Las comas se colocan al inicio al listar parámetros y todo debe alinearse verticalmente. |
| Mayúsculas | Palabras clave siempre en minúscula | Aplica para SQL y PL/SQL. En JavaScript usamos camelCase, y en MAYÚSCULAS para constantes. |
| Comentarios de Bloque | Separadores visuales normalizados | Nivel 1: -- ======= (Bloques vitales). Nivel 2: -- ------- (Lógica interna). |
| Deuda Técnica | Formato de TODOs rastreables | Obligatorio: -- TODO_[Iniciales]_<MES-DD-AÑO> [Descripción de lo pendiente]. |
| Nombrado BD | Uso obligatorio de Prefijos de Proyecto | Todas las tablas, vistas y paquetes inician con el acrónimo (ej. tf_tickets). |
| Variables PL/SQL | Prefijos que indican el “alcance” | l_ (local), p_ (parámetro entrada), o_ (salida), g_ (global), lc_ (constante). |
🗄️ 2. Diseño de Base de Datos y Creación de Tablas (DDL)
Una estructura sólida previene fallas crónicas dentro de nuestra interfaz. Aquí hacemos un énfasis particular en la automatización y seguridad.
| Objeto / Regla | Estándar de Implementación | Ejemplo de uso |
|---|---|---|
| Claves Primarias | Formato [tabla]_id y como Identity auto-incremental. |
ticket_id number generated by default on null as identity |
| Tipos de Datos Char | Todo string debe indicar los caracteres, nunca bytes. | varchar2(100 char) en vez del VARCHAR estándar asumiendo default. |
| Auditoría Global | Agregado mandatorio de columnas estándar de trazabilidad y Borrado Suave. | Campos active_yn, created_by, last_updated_on, etc. |
| 🌟 Uso de Triggers Compuestos | DESTACADO: La auditoría se delega ESTRICTAMENTE a Compound Triggers de base de datos. | Centraliza la lógica de auditoría sin que la aplicación en APEX tenga que modificar estas variables. |
| Constraints | Todas las restricciones requieren un prefijo lógico identificatorio. | fk_ (Llave foránea), uk_ (Única), ck_ (Check status = ‘Y/N’). |
💡 ¿Por qué resaltamos los Compound Triggers? Actualizar datos de auditoría o hacer Soft-Deletes desde la aplicación causa inconsistencias. Usar Compound Triggers previene los errores de mutación de tablas, centraliza las reglas de negocio, aumenta el rendimiento global y asegura que ni un solo registro escape de ser correctamente auditado con quién y cuándo lo modificó.
⚡ 3. SQL, Consultas y Lógica de Negocio (PL/SQL)
El motor principal de nuestro código DEBE poder leerse eficientemente de inicio a fin.
| Área | Estándar Obligatorio | Detalle o Aplicación |
|---|---|---|
| Consultas Limpias | Alineación tabular y comas al inicio de los SELECT. |
Hacer que los alias (AS) y nombres de columna estén a la misma altura horizontal. |
| Ciclos | Adiós cursores explícitos (OPEN/FETCH/CLOSE). | Exigimos el uso de FOR Loop (Cursores implícitos) reduciendo texto. |
| Diseño con WITH | Consultas complejas o Vistas se dividen en subconsultas (CTEs). | Nombrar siempre con el prefijo w_ (e.g. w_base, w_totales). |
| Packages y Tipos | Cero funciones estáticas (Standalones) sueltas en la base. Usar %type. |
En vez de variables quemadas VARCHAR2(50), usar ref. dinámica l_nombre empleado.nombres%type. |
| Logs Ocultos | Instrumentación robusta implementando librerías (logger). |
Documentar parámetros entrada, fin del procedimiento y el error OTHERS nativo sin asustar al usuario. |
🎨 4. Integración Práctica con Oracle APEX (Capa UX y Aplicación)
Las reglas que impiden que rompamos el hilo y seguridad desde la base de datos hasta lo que ve el cliente.
| Componente | Regla Establecida | Resultado Esperado en APEX |
|---|---|---|
| Manejo de Errores | Sustituir raise_application_error a favor de la API de APEX. |
Usar apex_error.add_error para que el mensaje caiga validado y limpio. |
| AJAX y Endpoints | Toda respuesta On-Demand debe imprimir formato JSON puro. | Implementación mediante código apex_json.write('success', true);. |
| Seguridad Procesos | Es imperativo utilizar las condiciones de Seguridad o Petición. | Todo “Process” TIENE que llevar una Server-side condition (ej. Request in SAVE). |
| Separación de Lógica | ¡Prohibido inyectar HTML explícito dentro un query SQL! | Devolver la data en crudo y emplear APEX Template Directives (ej. #STATUS#). |
| Paginación | Utilizar estructuras de cientos y decenas para asignar navegación. | Las listas de módulos se ubican (100) y sus detalles en subniveles (110). |
| Referencia UI | Todo debe llevar un Static ID según sufijo de su objeto. |
Regiones de Reporte Interactivo: ticketsIR; Botones estáticos (DELETE). |
📁 5. Estructura Oficial del Repositorio (Repo Structure)
🌟 Destacado: Un código impecable de nada sirve si el repositorio es un caos. Para asegurar compatibilidad con despliegues automatizados (CI/CD) y scripts, nuestro repositorio impone una arquitectura estricta e inquebrantable de carpetas:
| Directorio | Propósito Principal | Qué debe incluir en su interior |
|---|---|---|
/apex |
Aplicaciones | Los archivos .sql exportados directamente de Oracle APEX. |
/packages |
Lógica de Negocio | Especificación (.pks) y Cuerpo (.pkb) de los módulos de base de datos. |
/release |
Despliegue y CI/CD | Manifiestos versionados para gobernar el paso de Dev -> Test -> Prod. |
/data y /scripts |
Utilidades | Scripts para poblar Listas de Valores (LOVs) y scripts utilitarios de instalación. |
/triggers |
Automatizaciones | DDLs de base de datos, incluyendo nuestros vitales Triggers Compuestos. |
/www |
Archivos Estáticos | Todo el CSS, JavaScript e imágenes (Assets del frontend). |
¿Queres explorar los códigos fuente o colaborar? 🤝
Todo está consolidado y documentado con ejemplos reales. Te invito a pasar por el repositorio, clonar las pruebas o sugerir un Pull Request si encuentras áreas de mejora.
aflorestorres.com 