Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
PLAN DE CONVENCIONES
Y ESTNDARES DE CODIFICACIN
1. Generalidades
La transicin desde un diseo detallado a la codificacin, comienza cuando el
desarrollador escribe los mdulos que compilen en el lenguaje de programacin
seleccionado.
Esta transicin es obvia cuando existe un diseo que ha sido
confeccionado en forma detallada, lo que facilita la programacin.
Un cdigo fuente completo debe reflejar un estilo armonioso, como si un nico
programador hubiera escrito todo el cdigo de una sola vez.
La legibilidad del cdigo fuente repercute directamente en lo bien que un
programador comprende un sistema de software. La mantencin del cdigo es la facilidad
con que el sistema de software puede modificarse para aadirle nuevas caractersticas,
modificar las ya existentes, depurar errores, o mejorar el rendimiento.
Aunque la legibilidad y la mantencin son el resultado de muchos factores, una
faceta del desarrollo de software en la que todos los programadores influyen
especialmente es en la tcnica de codificacin.
El cdigo debe estar basado en los principios de:
-
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 1 de
rea de SQA
2. Documentacin Interna
Existen dos tipos de documentacin de software: interna y externa. La
documentacin externa como por ejemplo las especificaciones, los archivos de ayuda y
los documentos de diseo, se debe mantener fuera del cdigo fuente. La documentacin
interna est formada por los comentarios que el equipo de desarrollo escribe dentro del
cdigo fuente durante la fase de implementacin.
A continuacin se dan a conocer las normas y convenciones para mantener un
cdigo fuente estndar dentro del Departamento de Sistemas de Rabie S.A.
(1) Los comentarios deben ser en espaol.
(2) Los comentarios estarn situados arriba de cualquier instruccin que se desee
comentarizar.
(3) Evite aadir comentarios al final de una lnea de cdigo, porque lo hacen ms difcil de
leer. Por ejemplo:
If VariableA = VariableB Then
Comentario
VariableA
VariableD
VariableB
VariableC
as
as
as
as
String
Double
Integer
Integer
Comentario
Comentario
Comentario
Comentario
(4) Declare todas las variables en la parte superior de cada mdulo, procedimiento o
funcin, a excepcin de las variables que son utilizadas como ndices en bucles y que son
declaradas en la misma sentencia.
(5) Evite los comentarios recargados, como las lneas enteras de asteriscos u otro tipo de
carcter para comentarizar una instruccin simple. Por ejemplo:
/*****************************************************************
Si el cliente es nuevo, entonces
*****************************************************************/
Al contrario, utilice este tipo de comentarios, para indicar que toda una regin de cdigo
es importante para el mdulo, procedimiento y/o funcin. Por ejemplo, para sealar que
las siguientes lneas de cdigo, corresponden a una validacin escrita en MS SQL.
/********************************************************************
Condiciones de Retencin, Validacin tipo de Crdito
********************************************************************/
--Cliente es nuevo
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 2 de
rea de SQA
IF @ClienteNuevo = 1
BEGIN
.
(6) Use frases completas cuando escriba comentarios. Los comentarios deben aclarar el
cdigo, no aadirle ambigedad.
(7) Vaya comentando a la vez que programa, porque probablemente no tenga tiempo de
hacerlo ms tarde. Por otro lado, aunque tuviera oportunidad de revisar el cdigo que ha
escrito, lo que parece obvio hoy, es posible que tiempo despus no lo sea.
(8) Use los comentarios para explicar el propsito especfico del cdigo. No los use como
si fueran traducciones literales.
(9) Haga comentarios en el cdigo que est formado por bucles o bifurcaciones lgicas.
Se trata en estos casos de reas clave que ayudarn a los lectores del cdigo fuente a
una buena compresin de qu es lo que realiza el mdulo, procedimiento o funcin.
(10) Realice los comentarios en un estilo uniforme, respetando una puntuacin y
estructura coherentes a lo largo de toda la aplicacin.
(11) Se sugiere que separe los comentarios de sus delimitadores mediante espacios. Si
respeta estas normas, los comentarios sern ms claros y fciles de localizar si trabaja
sin indicaciones de color y si el carcter de comentario es demasiado pequeo.
Por ejemplo:
Esto es un comentario
Espacio en blanco
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 3 de
rea de SQA
3. Cabeceras
Al principio de cada procedimiento, funcin o mdulo, resulta til hacer comentarios
estndar, repetitivos y que indiquen el propsito de la rutina.
El formato para la Cabecera deber contener el caracter para comentar multi-lneas. Si el
lenguaje no lo posee, escribir el caracter en cada lnea.
Formato de Cabecera para Ms SQL
/************************************************************************
NOMBRE PROCEDIMIENTO
: (1 lnea)
OBJETIVO PROCEDIMIENTO : (hasta 4 lneas)
ENTRADAS
: (enumerar las entradas, separadas por comas
junto con una pequea descripcin dentro de parntesis)
SALIDAS
: (enumerar las salidas, separadas por comas)
FECHA CREACIN
: (incluya fecha, hora y autor)
FECHA LTIMA MODIFIC.
: (incluya fecha, hora y quien la realiz.
Copiar esta lnea hacia abajo, tantas veces hayan modificaciones)
************************************************************************/
: No tiene
FECHA CREACIN
: 28/04/2004
16:50
Paola Saez
V1.0 03-03-2006
Pgina 4 de
rea de SQA
4. Convenciones de Nombres
Desde el punto de vista de la programacin, un nombre nico sirve solamente para
diferenciar un elemento de otro. Los nombres expresivos funcionan como ayuda para el
lector, por eso, es lgico dar nombres que sean fciles de comprender.
4.1 Variables y Constantes
(1) Los nombres de todas las estructuras de cdigo deben ser en espaol.
(2) Los nombres de las variables, deben ser palabras significativas que den cuenta el
para qu servir esa variable. Aprovechando as, las nuevas herramientas, que
permiten nombres de variables con un largo mayor a 8 caracteres.
(3) Los nombres de las variables comprendern de una o ms palabras compuestas, cada
una de las cuales, su primera letra ser maysculas, mientras que las dems, sern
minsculas. En el nombre de la variable, no se usar guiones para separar las palabras.
Por ejemplo:
Direccion
NombreCliente
VendedorOctavaRegion
(4 Es recomendado que los nombres de las variable booleanas contengan una palabra
que describa su estado, por ejemplo: PuedeEliminarse, EsVendedor etc. Y siempre se
debe referir al estado verdadero, por ejemplo: TieneCredito, y no a su estado falso, por
ejemplo NoTieneCredito.
(5 Incluso para el caso de una variable de poco uso, que deba aparecer slo en unas
cuantas lneas de cdigo, emplee un nombre descriptivo. Utilice nombres de variables de
una sola letra, como i, j, k, l, m slo para ndices (ciclos For).
(6) En lo posible, no utilice nmeros o cadenas literales, como por ejemplo:
For i = 1 To 7.
En su lugar, emplee constantes con nombre, para que resulten fciles de mantener y
comprender. Un ejemplo en MS Visual Basic sera:
For i = 1 To CantidadClientes
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 5 de
rea de SQA
(1) Los nombres de las funciones, mdulos o procedimiento, mantendrn la primera letra
en mayscula de todas sus palabras.
Por ejemplo:
ValidarNotasVentas ()
CalcularComision ()
ImprimirInformeMensual ()
(2) Evite nombres imprecisos que permitan interpretaciones subjetivas, como por ejemplo
DefinirEsto(). Tales nombres contribuyen ms a la ambigedad que a la abstraccin.
(3) Utilice la tcnica verbo-sustantivo para nombrar procedimientos que ejecuten alguna
operacin en un determinado objeto. Evite usar preposiciones.
Por ejemplo:
CalcularTotal ()
GenerarInformeVentasDiario ()
GenerarInformeVentasMes ()
4.3 Parmetros
(1) Los parmetros siguen el mismo estndar de las variables.
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 6 de
rea de SQA
CantidadGiro.Text.Length = 0 Then
MsgBox("Ingrese la cantidad de dinero a girar.")
CantidadGiro.Focus()
Else
If GlosaGiro.Text.Length = 0 Then
MsgBox("Ingrese la glosa por este giro de dinero.")
GlosaGiro.Focus()
End If
End If
End If
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 7 de
rea de SQA
Llave apertura
HacerAlgo (ParametroA);
VariableB = VariableC + VariableD;
DisminuirUno (VariableA);
}
(4) Use un nico tipo de letra cuando publique versiones impresas del cdigo fuente.
(5) Se sugiere, que utilice espacios antes y despus de los operadores siempre que eso
no altere la sangra aplicada al cdigo.
Por ejemplo
CodigoVendedor = 1025, y no utilizar CodigoVendedor=1025
Espacios en Blanco
(6) Cuando tenga que dividir una lnea en varias, aclare que el cdigo sigue en la lnea de
ms abajo mediante un operador de concatenacin colocado al final de cada lnea, y no al
principio de la siguiente.
(7) No coloque ms de una instruccin por lnea, a excepcin de los bucles.
(8) Cuando escriba instrucciones SQL utilice solamente maysculas para las palabras
claves: SELECT, UPDATE, WHERE, FROM, BEGIN, IF, INNER JOIN, WHILE, entre otras.
(9) Coloque las clusulas SQL principales en lneas separadas, de modo que las
instrucciones sean ms fciles de leer y editar.
Por ejemplo:
SELECT
FROM
INNER JOIN
7,dbo.enotas_venta.not_num_nota_venta,art_cod_ean,not_linea,1
dbo.dnotas_venta (NOLOCK)
dbo.enotas_venta (NOLOCK) ON
dbo.dnotas_venta.not_num_nota_venta = dbo.enotas_venta.not_num_nota_venta
WHERE
dbo.dnotas_venta.not_num_nota_venta = @not_num_nota_venta
AND dbo.dnotas_venta.not_revisado = 0
AND art_cod_ean NOT IN
(SELECT DISTINCT art_cod_ean FROM dbo.marticulos (NOLOCK))
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 8 de
rea de SQA
(10) Evite llamadas a mtodos dentro de sentencias condicionales, esto hace que el
cdigo sea poco eficiente.
(11) Use el operador condicional ternario solo en casos triviales, cuando sean casos
complejos evtelo.
(12) En el caso de nombres de variables, funciones, procedimientos, mdulos, tablas,
entre otros, que posean una en su identificacin, sta deber ser reemplazada por
nia, nie, ni, nio, niu, segn corresponda.
Por ejemplo:
Dim AoActual as Integer
Dim CantidadAcompaantes as Integer
Deber ser:
Dim AnioActual as Integer
Dim CantidadAcompaniantes as Intenger
(13) Para los nombres de variables, funciones, procedimientos, mdulos, tablas, entre
otros, se podrn utilizar abreviaciones de palabras, siempre y cuando, sean lo ms
significativas y legibles posible.
Por ejemplo:
No utilizar
Variable que almacena el nombre de un cliente
Dim NCliente as String
Dim NCli as String
Dim NombreC as String
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 9 de
rea de SQA
6. Microsoft SQL Server
6.1 General
(1) Nunca use caracteres especiales para la creacin de nombres de objetos.
(2) Nunca utilice procedimientos almacenados recursivos.
(3) No ponga prefijos sp_ a los procedimientos almacenados, ya que se trata de un prefijo
reservado para la identificacin de procedimientos almacenados de sistemas.
(4) No ponga prefijos fn_ a las funciones definidas por el usuario, ya que se trata de un
prefijo reservado para funciones integradas.
(5) No ponga prefijos xp_ a los procedimientos almacenados extendidos, ya que se trata
de un prefijo reservado para la identificacin de procedimientos almacenados extendidos.
6.2 Formato de Nombres de Objetos
(1) Tablas
Formato: tb_XXXXX_Nnnn, donde:
XXXXX: es el nombre abreviado de la aplicacin que las utiliza, hasta las cinco primeras
letras. Por ejemplo GNV, SISTO, SLT, ERPFC (Solomon Financiero/Contable), ERPLD
(Solomon Logstica/Distribucin).
Nnnn: Nombre que representa lgicamente la informacin almacenada en la tabla
Ejemplo: tb_SAV_Direcciones
(2) Vistas
Formato: vt_XXXXX_Nnnn donde:
XXXXX: Es la sigla del sistema con un mximo de 5 caracteres, todo en letras
maysculas.
Nnnnn: Nombre lgico, del uso de la vista
Ejemplo: vt_SISTO_DatosVendedoresSeleccionados
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 10 de
rea de SQA
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 11 de
rea de SQA
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 12 de
rea de SQA
openrowset('sqloledb','sql-erp';'consulta';'socrates','select * from
rabieapp..xproducto')
21. Cada nueva forma de acceder a los datos debe ser informada y analizada antes de su
utilizacin.
Plan de Convenciones
y Estndares de Codificacin
V1.0 03-03-2006
Pgina 13 de