Nomenclatura de DocIRS para la Programación

Los lenguajes de programación utilizan formalización matemática, tanto en su estructura como en su simbología. Sus convenciones y usos se realizan especialmente utilizando leyes algebraicas, tales como la Lógica de Boole, particularmente Algebra de Proposiciones, Teoría de Conjuntos, Funciones (algebra y sus propiedades), Series Numéricas, Recursividad, etc. Esto implica que tener una notación acertada en programación, es fundamental.

Nótese que un programador debe comprender y expresarse a través de un lenguaje de alta programación. Este conocimiento aplicado y experimental puede ser adquirido por oficio práctico, intuición o por estudios formales.

Nota del Autor:

Personalmente postulo desde hace más de dos décadas, que antes de someter a los jóvenes a estudiar una serie de asignaturas matemáticas, se debería enseñar y practicar la Programación de Computadoras. Mi evidencia empírica, la he constatado a lo largo de los años con el Equipo de Desarrollo de DocIRS, donde hay programadores que jamás estudiaron matemática formal y son capaces de configurar un complejo algoritmo con estructuras algebraicas en un lenguaje de alta programación: Sólo usuando su intuición y oficio.(Ver Prólogo de "¿Cómo entender el Teorema de Bayes en forma simple?")

El concepto que estableció DocIRS para lograr calidad en las aplicaciones, también se aplica internamente en la programación. Es decir, que cuando se va construyendo un bloque de código, éste debe funcionar, debe ser eficiente y debe estar bien documentado.

Nótese que actualmente, los códigos de programación no son sólo para que los interprete la máquina, sino que también deben ser comunicados efectivamente. Comunicarlos implica que otros actores deberán comprenderlos y re-utilizarlos.

Según nuestra experiencia, la legibilidad es el criterio más sencillo para evaluar la calidad de un programa; si el programa es fácil de leer, probablemente es un buen programa; si es difícil de leer, no es un buen programa. (Ver Acerca del Estilo en Programación)

La idea central de definir una terminología estándar de DocIRS, es para lograr tanto en los códigos fuentes como en la notación de las bases de datos cumplir con los tres conceptos siguientes:

Consistencia	Utilizar siempre el mismo patrón en la asignación de variables, funciones, métodos, etc..evitando identificadores que están en conflicto con palabras claves de lenguajes de programación ampliamente utilizados.
Legibilidad	Identificar descriptivamente los objetos y su funcionalidad. Es decir, que la definición de variables, funciones, objetos, rutinas debe ser explicita a fin de que señale fácilmente su funcionalidad. La legibilidad es el criterio más sencillo para evaluar la calidad de un programa; si el programa es fácil de leer, probablemente es un buen programa; si es difícil de leer, no es un buen programa.
Documentación	Escribir autor, fecha, comentarios, ayuda, referencias, en cada función, bloque, etc.

El objetivo no es sólo la compresión por parte de otros programadores y aclaratorios para futuras referencias, sino que también deben apuntar hacia el estilo y la robotización (o máquina de generación de código en forma inteligente).

Ejemplo 1: ( Documentación)

<html>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <META NAME='Generator' CONTENT='RobotPrototipDocIRS'>
   <META NAME='Generator' CONTENT='Octubre2008@DocIRS'>
   <META NAME='DocIRS' CONTENT='PMO'>
<head>
<title>Ficha Proyecto~<%=strCodigoBusqueda%></title>
<script language="javascript" src="js/Validaciones.js"></script>
<script language="javascript" src="js/Ajax.js"></script>
<script language="javascript" src="js/FichaProyecto.js"></script>
<script language='javascript' src='js/cambia.js'></script>
<script language='javascript' src='js/xp_progress.js'></script>
<script language='vbscript' src='js/Validacion.js'></script>
…..

Creado por: Cristian Suarez Cáceres
'Fecha de Creación: 18/08/2004
'Funcion: Descripción de lo que hace la función
'Parametros: descripción de la finalidad de cada parámetro
… ...
End Function

Ejemplo2: (Función ASP)

gXMLseleccionEntradas = session("Seleccion")
gXMLidentificacionUsuario = session("Identificacion")

;mso-bidi-font-family: Arial;>if len(gXMLseleccionEntradas)=0 or len(session("Identificacion"))=0 then
response.Redirect("inicio.asp")
response.End()
if
..
GET
strFolio=request("folio")
strRegistro=request("in_pr")
..

POST
strFolio=request.form ("folio")
strRegistro=request.form ("in_pr")

..

‘’‘/* Donde RC significa Requerimientos de Cambio
function CuantosRC(pfolio)
Dim rsC
resultado=0
sSQL="SELECT * from mensajes where folio='" & pfolio & "'"
set rsC = server.CreateObject("ADODB.Recordset")
call AbrirConexion2()
rsC.open sSQL, gConn2
    if not rsC.eof then
Do While Not rsC.EOF
          mensaje=rsC("msg")
if Left(mensaje,3)="(RC" and rsC("folio")<>"Generico" then
resultado=resultado+1
end if
                               rsC.MoveNext
                               Loop
                end if
                rsC.close
    call CerrarConexion2()
    set rsC = nothing
CuantosRC=resultado
end function

Ejemplo 3: (función dom javascript)

function HaceDesaparecerFilasVacias(){
///////////////// desaparecen fila vacías hasta actualizacion de la pagina
//////////////// notese que admite que se entre una de las dos fechas Iniciacial o Final. Solo desaparece cuando ambas estan vacias
for (var j=2;j<10; j++)
    {
                var obj1="txtFechaInicioHito" + j
                var obj2="txtFechaFinHito" + j
    obj1=document.getElementById(obj1).value
                obj2=document.getElementById(obj2).value

                if(obj1.length==0 && obj2.length==0)

                {
                               for (var k=j;k<10; k++)
                              {
var objFila="tr_fila" + k
document.getElementById(objFila).style.display="none"
}
                }
    }
///////////
}

Sintaxis Nombre Objetos

La notación de DocIRS, sigue los patrones definiendo prefijos para cada tipo de datos y según el ámbito de las variables. Es decir, entregar la mayor información posible mediante el nombre de la variable, método o función definiendo en ella un prefijo que identifique su tipo de dato y ámbito.

Objetos, Controles y Tipos	Sintaxis Nombre Objetos

Clases	cls<id name>
Módulos	Mod<id name
formularios	frm<id name>
Combobox	cbo<id name>

Datagrid	grd<id name>
Listbox	lst<id name>
Radiobutton	rd< option id name>
checkboxes	chk< checkname>
Textboxes	txt< textname>
Area	txt<id name>
Button, Submit	cmd<id name>
Table	tbl<id name>
Tr	tr<id name>
Td	td<id name>
Span	sp<id name>
hidden	h<id name >

Métodos	m_<id name>
Controles	c_<id name>
Utilidades	u_<id name>

Integer	int< nombre >
Long	lng< nombre >
Bolean	bln< nombre >
Object	obj< nombre >
String	str< nombre >
Double	dbl< nombre >

Parámetros	str<nombre>
Constantes	ct<nombre>
Variable globales	var glb<nombre>

Ejemplos de uso de la sintaxis: (Nótese que siempre se utiliza el id y el name con las misma asignación)

<input type='text'
id="txtFechaInicioProyecto"
name="txtFechaInicioProyecto"
maxlength='10' size='12'
style='text-align: center'
onKeyPress=" javascript:SubCampoKeyPress('0-9/-'); DiferenciaDiasEntreFechas()"

...

...

Estructura de los Sitios Web

Cada aplicación Web cuenta con tres tipos de ambiente: Desarrollo, Prueba y Producción. Los tres ambientes poseen Carpetas (conteniendo las páginas) y Base de Datos independientes, que son diferenciadas con la siguiente sintaxis:

Ambiente	Carpeta	Base de Datos
Desarrollo	<id sitio>D	<id sitio>D
Prueba	<id sitio>P	<id sitio>P
Producción	<id sitio>	<id sitio>

Las páginas Web de la aplicación, están distribuidas en distintas carpetas, según la funcionalidad que estas cumplen. Según lo anterior, las páginas se clasifican en:

Navegación: Corresponde a las páginas que forman parte de la navegación de la aplicación (capa de Presentación) y se encuentran en la carpeta raíz de cada sitio Web.
Controles: Corresponde a las páginas que se relacionan directamente con la base de datos (capa de Datos). Estas páginas, contienen funciones que leen y graban en la base de datos, siempre a través de procedimientos almacenados. Cada página-control interactúa con una entidad particular en la base de datos, es decir: Para la entidad Cliente (que en el modelo de datos puede estar representado por una o más tablas) se utiliza un control que lleva por nombre “c_Cliente.asp”, desde el cual se realizan todas las lecturas y grabaciones que correspondan únicamente a la entidad Cliente. Estas páginas se encuentran dentro de la carpeta “Controles” que se ubica en el directorio raíz del sitio Web.
Métodos: Corresponde a las páginas que contienen las lógicas de negocio de la aplicación (capa de Negocio). Estas páginas, se encargan de la comunicación entre las páginas de “Navegación” y los “Controles”, transformación de datos (para la lectura o grabación en los formatos que se requieran), cálculos y funcionalidades propias del negocio. Estas páginas se encuentran dentro de la carpeta “Métodos” que se ubica en el directorio raíz del sitio Web.

Base de Datos

La base de datos y cada uno de sus objetos poseen también una nomenclatura y una forma de documentación.

Los elementos de una base de dato poseen la siguiente nomenclatura:

Elemento	Nomenclatura
tabla	t<id tabla>
Relaciones entre tablas	FK<correlativo>_t<id tabla origen>
Indices Alternativos (Llave única)	XAK<correlativo>_t<id tabla origen>
Indices Alternativos (Llave NO única)	XIE<correlativo>_t<id tabla origen>
vista	vss<id vista>
Procedimiento Almacenado de Lectura	svc_< id procedimiento >
Procedimiento Almacenado de Grabación	sva_< id procedimiento >
Procedimiento Almacenado de Eliminación	sve_<id procedimiento>
DTS Ambiente de Desarrollo	<id base de datos>D_<id dts>
Funciones definidas por el Usuario	f_<id función>
DTS Ambiente de Prueba	<id base de datos>P_<id dts>
DTS Ambiente de Producción	<id base de datos>_<id dts>

Los procedimientos almacenados se documentan de la siguiente manera:

-- Autor	Daniel Toro Zamorano / DocIRS
-- Objetivo	Trae un XML con los Datos del Caso Judicial para Autorizar la Facturación Inter Empresas
-- Fecha Creacion	06.04.2009
-- Nombre Actualizador
-- Fecha Actualizacion



Entonces, el procedimiento almacenado se ve de la siguiente forma: CREATE PROCEDURE svc_TraeXMLDeudor @nRutDeudor numeric(10) AS -- Autor : Cristian Suárez Cáceres / Docirs -- Objetivo : Trae un XML con los Datos el Deudor -- Fecha Creación : 15.04.2009 -- Nombre Actualizador : -- Fecha Actualizacion : select nRutDeudor, sDvRutDeudor, sNombreDeudor from tDeudor Deudor where nRutDeudor = @nRutDeudor for xml auto, elements

Nomenclatura de los campos en el modelamiento de Base de Datos

Campo	Descripción	Ejemplo
id<nombre campo>	Código que se utiliza principalmente como identificador de un registro.	idComuna
s<nombre campo>	Campo de tipo String	sObservacion
f<nombre campo>	Campo de tipo DateTime	fIngreso
idr<nombre campo>	Campo de tipo Indicador, que se utiliza principalmente para los campos de tipo “Si” o “No” y que se define como BIT.	idrSolicitudEnviada
p<nombre campo>	Campo que se utiliza para identificar un parámetro con un número opciones limitadas.	pPeriodicidad 1 = Diario 2 = Semanal 3 = Mensual 4 = Anual
n<nombre campo>	Campo de tipo numérico.	nMontoLiquido

Artículos Relacionados


	Nomenclatura de DocIRS para la Programación José Enrique González Cornejo 24 de abril 2009	No existen más que dos reglas para escribir: tener algo que decir y decirlo. Oscar Wilde