Nomenclatura de DocIRS para la Programación
José Enrique González Cornejo y Cristian Suárez C.
24 de abril 2009

No existen más que dos reglas para escribir: tener algo que decir y decirlo.
Oscar Wilde

 

 

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 Bool, 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.

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)

 

<form id="FrmFichaProyecto" name="FrmFichaProyecto" method='Post'>

 


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

...


 

 <table id="tbl_editor" name="tbl_editor" …..>
<tr id=”tr_fila1” name=”tr_fila1”>
 <td id="td_titulo_ficha" name="td_titulo_ficha" bgcolor=#D3D3D3>

...

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