INST Estndar Codificacin SQL y PL-SQL

Convenciones de nombres y estndares de codificacin para SQL y PL/SQL

Objetivo:
Establecer pautas para estandarizar los nombres de objetos Oracle y la confeccin de cdigo SQL y PL/SQL, para lograr:
cdigo fcil de entender y, por lo tanto, de mantener (claridad)
simplificar la decisin al momento de establecer nombres
uniformidad en el criterio utilizado por todos los integrantes de SziCom
Convencin de nombres de objetos:
General:
Todos los nombres de objetos de la base de datos se debern escribir en maysculas.
Se utilizarn guiones bajos (_) para separar palabras.
Se evitarn, en lo posible, las abreviaturas.
Tablas:
Se han adoptado algunas nomenclaturas para prefijar los nombres de las tablas:
Prefijo Significado Ejemplo
NTC_ Nominacin Transporte Cliente DESPACHO.NTC_NOMINACION
DCG_ Desbalance Cliente Gas DESPACHO.DCG_AJUSTE_INYECCION
DCL_ Desbalance Cliente DESPACHO.DCL_AJUSTE_CONSUMO
ABI_ Tablas que se alimentan directamente con datos del ABI de TGN ABI_BAL, ABI_COMPENSACION
SPAC_ Tablas que se alimentan directamente con datos del SPAC de TGS SPAC_ASIGNACION_PUNTO
MV_ Tablas Snapshot de vistas materializadas MV_CONSUMO
Toda tabla deber tener un breve comentario que describa su contenido.
Columnas:
Nombre del objeto Comentario Ejemplo
ID_nombre_tabla Prefijo ID (aplica a campos enteros) ID_CLIENTE; ID_PUNTO
FH_accin Prefijo FH indica fecha y hora FH_ENVIADO
NOMINADO Implica el prefijo VOLUMEN NTC_NOMINACION.NOMINADO
Toda columna deber tener un breve comentario explicativo.
Otras convenciones:
Los campos que correspondan a valores del tipo se definirn como CHAR(1) y luego mediante una SI/NO, VERDADERO/FALSO,
constraint se limitar el contenido a las letras S o N.
Los campos que registren el que realiz la accin, se denominarn USUARIO, sern del tipo VARCHAR2(32), pudiendo usuario Oracle
o no tener como default: USER.
Los campos se denominarn ANIO y se definirn como NUMBER(4). Ao
Cuando una columna refiera al ID de otra tabla (FOREIGN KEY), deber tener (en lo posible) el mismo nombre que el campo ID de la
tabla referenciada. Esto facilita que muchas herramientas de generacin de diagramas establezcan de manera automtica las relaciones
entre tablas.
Todo campo "tipo" que tenga ms de 3 (tres) estados posibles deber transformarse en un campo ID que deber referenciar a una tabla
TIPO_X convenientemente creada a tal efecto.
Constraints:
El espacio de nombre de las contraints es el del esquema.
Prefijo Significado Ejemplo
PK_xxx Clave primaria, xxx es el nombre de la tabla PK_CLIENTE
UK_xxx_yyy Indice nico sobre la tabla xxx y los campos yyy UK_CLIENTE_NEMONICO
FK_xxx_yyy Foreign Key de la tabla xxx columna yyy FK_CESION_ID_CAMARA
NN_xxx_yyy El campo yyy de la tabla xxx no puede ser nulo NN_CLIENTE_FECHA_ALTA
POS_xxx_yyy El campo yyy de la tabla xxx debe ser positivo TRANSPORTE.POS_TARIFA_TARIFA_FIRME
SN_xxx_yyy El campo yyy de la tabla xxx debe contener S o N DESPACHO.SN_NOMINACION_VERSION_CERRADA
CHK_xxx_yyy El campo yyy de la tabla xxx debe cumplir el CHECK CHK_BALANCE_MES_MES
Se recomienda no crear las constraints en el comando SQL CREATE TABLE, ya que stas se generan como System Named.
Si se utiliza el TOAD, no utilizar las columnas PK y NOT NULL de la grilla de armado de tablas, ya que las constraints resultantes se generan
como System Named.
Triggers:
La primera letra del nombre indicar el momento en que disparar el trigger:
B Before (Antes)
After (Despus) A
Agregado de la letra
Si se trata de un trigger BEFORE o AFTER STATEMENT, si no se indica se supone FOR EACH ROW. S
Luego, las siguientes letras indicarn en el orden que se expone, qu acciones sobre la tabla involucrada disparn los triggers:
I Insert
Update U
Delete D
A continuacin, el nombre de la tabla correspondiente.
Ejemplos:
Nombre Significado
BIU_TARIFA Before Insert/Update (for each row) en la tabla TARIFA
BSIUD_TARIFA Before Statement Insert/Update/Delete en la tabla TARIFA
AIU_TARIFA After Insert/Update (for each row) en la tabla TARIFA
Secuencias:
Se prefijar y luego se indicar el nombre de la tabla que tiene uno o ms triggers que a su vez utilizan la secuencia. SEQ_
Ejemplos:
SEQ_CAMARA_BALANCE
SEQ_GNC_CONTRATO_GAS
Packages:
Se prefijar y luego se indicar con una o ms palabras el mbito al que corresponde el package. PK_
Ejemplos:
PK_NOMINACION
PK_CONTROL_FACTURACION
PK_CONTRATO
PK_VENTANA
Vistas:
Los nombres de las vistas se prefijarn segn el siguiente criterio:
Prefijo Significado
V_ Vista estndar
VA_ Vista de valores acumulados
MV_ Vista materializada
VD_ Vista para desnormalizar tablas
X_, XX_ Vistas intermedias, utilizadas por lo general para no incluir subquerys en la vista final
Al momento de redactar las vistas:
Introducir un breve comentario explicativo, a rengln siguiente de la clusula SELECT y antes de comezar a enumerar los campos.
Prefijar las tablas/vistas utilizadas en la seleccin, con el esquema al que pertenecen.
Cuando se trate de joins de tablas o vistas, establecer alias y utilizarlos al referenciar los campos, tanto en la clusula SELECT como en
las clsulas WHERE, ORDER BY o GROUP BY.
Estndares de codificacin para SQL y PL/SQL:
Notacin:
Prefijo Significado Ejemplo
p Parmetro de funcin/procedimiento pID_CLIENTE, pDIA_OPERATIVO
v Variable local al procedimiento/funcin vCONT, vFECHA_DESDE
g Variable global del package gDIA_OPERATIVO
k Constante kID_MERCADO_GU, kID_DISTCO
c Cursor cCLIENTES_ACTIVOS
e Variable del tipo EXCEPTION eNO_VIGENTE
r Registro, fila de un cursor, tupla rCLIENTE_ACTIVO
t Tipo tARR_NOMINACION
a Array aNOMINACION
Comentarios:
Cabecera de mtodos:
Es obligatorio escribir un comentario en la cabecera de un mtodo (procedimiento o funcin). Se debe indicar al inicio del comentario las
iniciales del programador que cre o modific el mtodo.
El comentario no debe exceder las 2 lneas. Si se requiere ms detalle se deber recurrir a la especificacin que motiv la creacin o
cambio del mtodo, que seguramente tendr el contexto.
Historial de cambios: limitarlos a una lnea por cambio y si una lnea no es suficiente, hacer referencia al requerimiento (issue) que dio
origen al cambio. Si son varios issues se indicarn.
Ejemplo:
-- Replicar el contrato para el cliente con los mismos servicios y la misma vigencia
-- Autor. CSZ (20/12/2009)-Tomado de la version 2.
-- Modif. ACM (20/01/2009)-Replicar adecuadamente las tarifas y replicar volumenes.
-- RAV (02/02/2009)-Issue DESPACHO-153.
Nota: Este tipo de comentario dejar de utilizarse cuando se implemente svn para Oracle.
Comentarios en un bloque interno de cdigo:
Valen las mismas consideraciones que para los comentarios de cabecera. Por ejemplo: descripcin de un cursor.
Comentarios adicionales:
Corresponden a informacin que no es evidente, que no se puede deducir del comentario estandar y que el programador considera importante.
Ejemplos:
-- Controlar que no se haya creado antes la misma cesin.
-- Recorremos la lista de clientes que reciben, asignando hasta terminar el excedente
Pautas generales:
Nombrar los objetos de cada esquema con el prefijo del esquema, aunque sea redundante.
Ejemplos:
SELECT ID_CLIENTE, NEMONICO
FROM CI.CLIENTE
vFIRME_CONTRATADO := CI.PK_CONTRATO.FIRME_CONTRATADO;
Utilizar tipo de variables enteras cuando los operandos sean enteros y el resultado un entero (PLS_INTEGER).
Evitar el uso de "Nmeros mgicos". Definir constantes con nombres representativos, prefijadas con . k
Evitar el uso de EXIT o RETURN para salir de un ciclo FOR o WHILE.
Utilizar nombres de variables en los ciclos que aporten mayor informacin que el simple uso de I, J, K, etc.
Ejemplos:
-- Cuando no es un simple conteo de iteraciones...
FOR vMES IN 1..12 LOOP
-- Cuando se trata de un registro de un cursor...
FOR rCLIENTE IN cCLIENTES_ACTIVOS LOOP
Todo procedimiento o funcin deber incluirse en un package afin.
Escribir el nombre del procedimiento o funcin en el END de cierre (permite diferenciarlo fcilmente de otros ENDs del cdigo).
Ejemplo:
END BORRAR_APERTURA_NTC_NOM_CLIE;
Longitud mxima para un procedimiento/funcin/trigger: 30 lneas de cdigo.
Evitar el uso de IF para asignar valores a variables booleanas.
Ejemplo:
-- Usar:
vVENCIDO := vFECHA_HASTA <= vFECHA_LIMITE;
-- En lugar de:
IF vFECHA_HASTA <= vFECHA_LIMITE
THEN
vVENCIDO := TRUE;
ELSE
vVENCIDO := FALSE;
END IF;
Utilizar variables booleanas para mejorar la legibilidad.
Ejemplo:
vELEGIBLE_PARA_AUMENTO := rEMP.SALARIO BETWEEN 10000 AND 50000
AND ESTADO_EMPLEADO(rEMP.ID_EMPLEADO) = 'N'
AND MONTHS_BETWEEN (rEMP.FECHA_ALTA, SYSDATE) > 10;
IF vELEGIBLE_PARA_AUMENTO
THEN
DAR_AUMENTO(rEMP.ID_EMPLEADO);
END IF;
Indentacin (ejemplos):
Al definir variables:
vVERSION PLS_INTEGER;
vID_TIPO_CONSUMO PLS_INTEGER;
vCLAVE VARCHAR2(255);
eTIPO_CONSUMO EXCEPTION;
eVERSION EXCEPTION;
vFH_PROCESO DATE;
vDESDE DATE;
vHASTA DATE;
vTIPO VARCHAR2(12);
Al escribir DMLs:
SELECT CL.ID_CLIENTE, CL.NEMONICO,
CT.ID_CONTRATO, CT.FECHA_INICIO, CT.FECHA_FIN
FROM CI.CLIENTE CL,
CI.CONTRATO CT
WHERE CL.ID_CONTRATO = CT.ID_CONTRATO
AND CT.FECHA_FIN < SYSDATE;
INSERT INTO BALANCE.LOG_PROCESO
( FH_PROCESO, ID_PROCESO, ID_TIPO_ERROR, DETALLE)
VALUES
( SYSDATE, vPROCESO, vERROR, vDETALLE);
UPDATE CI.CESION_DIA
SET APERTURA_NOMINADO = NOMINADO,
APERTURA_AUTORIZADO = AUTORIZADO,
ASIGNADO = NULL
WHERE DIA_OPERATIVO = vDIA_OPERATIVO
AND ID_CESION IN (SELECT C.ID_CESION
FROM CI.V_CESION C
WHERE C.ID_CLIENTE_RECIBE = vID_CLIENTE);
DELETE BALANCE.CONSUMO_LOCALIDAD
WHERE ANIO = vANIO
AND MES = vMES
AND VERSION = vVERSION
AND ID_LOCALIDAD = TC.ID_LOCALIDAD
AND ID_TIPO_CONSUMO = vID_TIPO_CONSUMO;
Al escribir IFs:
IF a = 1
AND ( b = 2
OR c = 3
OR d = 4 )
THEN
accion_verdadero
ELSE
accion_falso
END IF;
Al asignar valores:
vEXCEDENTE := vEXCEDENTE + GREATEST(0, TC.VOLUMEN);
vFALTANTE := vFALTANTE - LEAST(0, TC.VOLUMEN);
Al definir procedimientos o funciones:
-- Breve comentario explicativo
FUNCTION AUTORIZADO_INICIAL
(pSOLICITADO PLS_INTEGER,
pFIRME PLS_INTEGER,
pGAS_TOTAL PLS_INTEGER,
pTIENE_TI PLS_INTEGER)
RETURN PLS_INTEGER IS
Manejo de los errores - Excepciones:
Texto en las excepciones: Si el mensaje hace referencia a un objeto que causa el error, el objeto debe estar identificado por el nombre.
Ejemplo:
'No est definido el punto ' || vNombrePunto || ' en la tabla RED.PUNTO'