estándares de programación

24
Estándares de Programación CNTI Estándares de Programación Versión: 0.0.1 Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, Caracas Telf. 0212-7718800. Fax 0212-771.86.48 Sitio Web: www.cnti.gob.ve 1 de 24

Upload: abdiasmalave

Post on 17-Feb-2015

32 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Estándares de Programación

Estándares de Programación CNTI

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve1 de 24

Page 2: Estándares de Programación

Índice de contenido

1. Introducción...........................................................................................................................3

2. Estándares y Convenciones de Nombre................................................................................4

Convención de Nombres para Elementos UI...........................................................................7Convención de Nombres para Elementos UI...........................................................................7Convención de Nombres para Elementos UI...........................................................................7Convención de Nombres para Elementos UI...........................................................................7

3. Indentación............................................................................................................................8

4. Buenas Prácticas de Programación.......................................................................................9

Declaraciones..........................................................................................................................9Declaraciones..........................................................................................................................9Declaraciones..........................................................................................................................9Declaraciones..........................................................................................................................9Sentencias o Instrucciones....................................................................................................10Sentencias o Instrucciones....................................................................................................10Sentencias o Instrucciones....................................................................................................10Sentencias o Instrucciones....................................................................................................10Hábitos de Programación.......................................................................................................11Hábitos de Programación.......................................................................................................11Hábitos de Programación.......................................................................................................11Hábitos de Programación.......................................................................................................11Interacción con Base de Datos..............................................................................................13Interacción con Base de Datos..............................................................................................13Interacción con Base de Datos..............................................................................................13Interacción con Base de Datos..............................................................................................13Manejo de Mensajes..............................................................................................................14

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve2 de 24

Page 3: Estándares de Programación

Manejo de Mensajes..............................................................................................................14Manejo de Mensajes..............................................................................................................14Manejo de Mensajes..............................................................................................................14

5. Arquitectura ........................................................................................................................15

6. Programación Web..............................................................................................................15

7. Comentarios........................................................................................................................15

8. Manejo de Excepciones.......................................................................................................16

9. Parametrización y Configuración de una aplicación............................................................17

10. Sobre la organización de una aplicación a nivel de Sistema de Archivos..........................17

11. Sobre las Estructuras de Datos (Persistencia)...................................................................19

12. Sobre la Seguridad............................................................................................................22

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve3 de 24

Page 4: Estándares de Programación

Estándares de Programación CNTI

1. Introducción

Este documento se ha realizado con la finalidad de definir estándares de programación y buenas prácticas para ser tomadas como referencia para el desarrollo de aplicaciones.

Existen diversos criterios para definir una buena codificación. Entre los criterios más importantes se encuentran: Confiabilidad, Mantenibilidad y Eficiencia.

La mayoría de los desarrolladores se esfuerzan por la realización de un código eficiente para proporcionar un mayor rendimiento, comprometiendo la confiabilidad y facilidad de mantenimiento del mismo. Si el código no es confiable y mantenible, se invierte mucho tiempo en la detección de los problemas en el momento de resolver alguna falla, tratando de entender el código, entre otras cosas.

Para evitar estos inconvenientes, es aconsejable seguir estándares y buenas prácticas de programación. Las mismas serán descritas a lo largo del documento.

2. Estándares y Convenciones de Nombre

Las convenciones de nombres hacen los programas más entendibles, es decir, más fáciles de leer. También pueden dar información sobre la función de un identificador, por ejemplo, si es una constante, un método, una variable, entre otros.

Es importante que se use la convención de manera consistente, lo contrario hace que el código sea difícil de seguir. Por ejemplo, el uso de variables a, abc, x, deben evitarse a toda costa. Se recomienda no usar abreviaturas, a menos que

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve4 de 24

Page 5: Estándares de Programación

sea una abreviatura clara y ampliamente usada en el área de aplicación de software como CPU, URL, entre otras. Hay casos que contradicen esta recomendación, como el uso de contadores o índices para iterar sobre una estructura de datos (i, j, k), ya que históricamente se han usado así.

Los nombres pueden estar en inglés o español. Se debe evitar es usar distintos idiomas a la vez, es decir, nombres en inglés y español en la misma clase.

A continuación se presenta un cuadro con los estándares de nombres:

Tipo de Identificador

Reglas para nombrar Ejemplos

Programas

Los nombres de los archivos de código fuente deben basarse en palabras o combinaciones de palabras que expresen de alguna forma el propósito intrínseco al archivo. Si el archivo contiene una clase, debe llevar el nombre de la clase. La primera letra de cada palabra debe ir en mayúscula, y el resto en minúscula.

Presidencia.htmlPresupuestoAnual.javaRegistrarUsuario.php

Paquetes (cuando aplique)

Se escribe siempre en minúscula y por lo general se usa el nombre del dominio de internet de la organización. Los subsecuentes componentes del nombre varían de acuerdo a la organización de la aplicación

Para el caso del CNTI podría ser:

ve.cnti.genportal.plantillas

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve5 de 24

Page 6: Estándares de Programación

ClasesLos nombres de las clases deben ser sustantivos (una clase es una plantilla, a partir de la cual se instancian objetos. Los nombres de los objetos en la vida real son sustantivos). Cuando los nombres son compuestos, la primera letra de cada palabra que los forman deben ir en mayúscula. Los nombres de las clases deben ser simples y descriptivos. Se recomienda usar palabras completas, evitar acrónimos y abreviaturas (a no ser que la abreviatura sea mucho más conocida que el nombre completo, ejemplo URL o HTML)

class Usuario

class UsuarioAdministrador

Interfaces (Cuando aplique)

Siguen la misma regla que las clases

interfaz Almacén

interfaz VistaGenerica

Métodos / Funciones

Los métodos o funciones deben ser verbos. El nombre de los métodos y funciones debe ser en minúscula. Cuando los nombres son compuestos, la primera letra de la primera palabra debe ser en minúscula y la primera letra de las siguientes palabras que lo forman en mayúscula. Los métodos y funciones deben ser cortos y fáciles de entender., y

ejecutar()

agregarUsuario()

function getPassword()

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve6 de 24

Page 7: Estándares de Programación

deben hacer una sola cosa.

Variables

Todas las variables empezarán con minúscula. Las palabras internas que lo forman (si son compuestas) empiezan con su primera letra en mayúscula. Los nombres de las variables deben ser cortos y con significado. La elección del nombre de una variable debe ser un mnemónico, designado para indicar a un observador casual su función. Evitar el uso de abreviaturas sin significado alguno, como a, b, dd, entre otros. Esto es recomendado solamente cuando la abreviatura es muy conocida como tmp para temporal o i,j,k para índices. Es preferible un nombre de variable extenso pero con significado claro.

int tmp

float impuesto

double totalSinIVA

$montoConIVa

ConstantesDeben ir totalmente en mayúscula separando las palabras con un underscore (_)

static final int ANCHURA_MINIMA = 4;

static final int IVA = 0,09;

$IVA = 0,9;

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve7 de 24

Page 8: Estándares de Programación

• Convención de Nombres para Elementos UI

Para el manejo de elementos UI, también se debe considerar estandarizar los Nombres. Existen elementos que son manejados por un lenguaje en particular, sin embargo, hay algunos que son comunes en la mayoría de los lenguajes. El nombre de estos elementos debe tener un prefijo que describa el elemento en minúscula, seguido de un nombre significativo que defina el (los) dato(s) que representa. Ej.: txtNombre (Para un text box que guarde el nombre de un usuario).

A continuación se presenta una tabla con los elementos UI más utilizados y sus prefijos:

Elemento UI PrefijoPrefijo

Label lbl

TextBox txt

DataGrid dtg

Button btn

ImageButton imb

ListBox lst

DataList dtl

Checkbox chk

RadioButton rdo

Image img

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve8 de 24

Page 9: Estándares de Programación

Panel pnl

Table tbl

3. Indentación

Se debe utilizar como unidad de indentación un tabulador (el cual debe ser de 8 espacios). Evitar las líneas de 80 caracteres ya que no son manejados por algunos editores.

Cuando una expresión no cabe en una línea, se debe hacer el “salto de línea” de acuerdo a los siguientes principios:

(a)Romper después de una coma.

(b)Romper antes de un operador.

(c) Utilizar rupturas de alto nivel (más a la derecha que el “padre”) y no las de bajo nivel (más a la izquierda que el “padre”).

(d)Alinear la nueva línea con el comienzo de la expresión al mismo nivel de la línea anterior.

(e)Si las reglas anteriores llevan a un código confuso o a código que se aglomera al margen derecho, identar solo un tabulador (8 espacios) en su lugar.

Hay que procurar no mezclar inadecuadamente tabulaciones con espacios.

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve9 de 24

Page 10: Estándares de Programación

Por lo que se recomienda usar solo tabulador. Las sangrías de tabulador (8 espacios) hacen que el código sea más fácil de leer y tiene un beneficio añadido de señalar el código anidado.

4. Buenas Prácticas de Programación

• Declaraciones

(a)Se debe colocar una declaración por línea.

(b)Inicializar las variables locales donde sean declaradas. Algunos errores de compilación se producen cuando una variable es declarada sin ser inicializada.

(c) Colocar la declaración/inicialización de las variables solo al principio de un bloque. No esperar a usarla por primera vez para declararla ya que esto puede dar pie a confusiones. La única excepción a esta regla son los índices de los bucles for.

(d)Evitar las declaraciones locales que oculten declaraciones de niveles superiores. Por ejemplo no declarar la misma variable en un bloque interno. Ejemplo:

int cuenta;

......

miMetodo(){

if (condición) {

int cuenta = 0;

}

}

(e)En la programación orientada a objetos, no hacer los atributos públicos ni

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve10 de 24

Page 11: Estándares de Programación

protegidos, estos deben ser siempre privados. Para acceder al valor de los mismos, se deben crear métodos públicos.

• Sentencias o Instrucciones

(a)Debe haber solo una sentencia por línea y debe ser lo más simple posible. Si una sentencia es muy grande, debe ser dividida aunque ocupe varias líneas. se pretende mantener la claridad ante todo.

(b)Siempre se deben usar las llaves de apertura y cierre en las sentencias de código que lo amerite, así contenga solo una instrucción. Ejemplo:

if (condición) {

sentencias;

}

else{

sentencias;

}

Lo mismo aplica para sentencias For, While y Switch.

(c) En una sentencia Swtich, todos los Case deben incluir la sentencia break; cuando ocurran excepciones de esta regla, se debe indicar un comentario donde la sentencia break se encontraría normalmente.

(d)Cada sentencia Switch debe incluir un caso por defecto. El break en el caso por defecto es redundante, pero prevee que se propague por error si luego se añade otro caso.

• Hábitos de Programación

(a)Evitar el uso de objetos para acceder a una variable o método de tipo estático. Ejemplo:

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve11 de 24

Page 12: Estándares de Programación

UnaClase.metodoDeClase(); // OK

unObjeto.metodoDeClase(); // EVITAR

(b)Nunca usar números directamente sobre operaciones, en su lugar declarar estos valores como constantes. Ejemplo:

subtotal = precio * IVA; // OK

subtotal = precio * 0,9; // EVITAR

(c) Evitar asignar el mismo valor a varias variables en la misma sentencia, ya que esto dificulta su lectura. Ejemplo:

charInicial = charFinal = 'a'; // EVITAR

(d)No usar asignaciones embebidas. Ejemplo:

d = ( a = b + c ) + r; // EVITAR

(e)Usar paréntesis en expresiones que implican distintos operadores para evitar problemas con errores de precedencia de los mismos, inclusive si parece claro el orden de precedencia de los operadores. Ejemplo:

if ( ( a == b ) && ( c==d ) ) // OK

if ( a == b && c==d ) // EVITAR

(f) Es recomendable utilizar dos líneas en blanco entre declaraciones de clases. además de una línea en blanco entre: métodos, declaraciones de variables

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve12 de 24

Page 13: Estándares de Programación

y la primera sentencia del método, antes de un comentario y entre secciones lógicas de código cuando esto mejore su legibilidad y comprensión.

(g)Todas las operaciones aritméticas deben ir con espacios en blanco separando operandos de operadores. Ejemplo:

a = ( b + c ) / ( c * d ); // OK

(h)Se debe dejar un espacio en blanco después de cada coma al declarar los parámetros de un método.

(i) Hay que mantener la coherencia y consistencia en el uso de los nombres de las clases, variables y métodos, entre otros. Evitar el uso de nombres cortos y confusos.

(j) Evitar escribir métodos muy largos. Un método regularmente tiene de 1 a 25 líneas de código. Si un método tiene más de 25 líneas de código, se debe considerar separarlo en varios métodos.

(k)Un método debe hacer solo un trabajo. No combinar más de un trabajo en un método simple, inclusive si estos trabajos son muy pequeños.

(l) Siempre hay que estar atento con los valores inesperados en las condiciones. Por ejemplo, si se está usando un parámetro que puede tener solo 2 valores, no suponer que si en uno no coincide, es automáticamente el otro. Ejemplo:

if (tipoPersona == 'V') {

sentencias de Vendedor;

}

else if (tipoPersona == 'C'){ // OK

sentencias de Cliente;

}

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve13 de 24

Page 14: Estándares de Programación

(m)Los Strings se deben convertir a mayúscula o a minúscula antes de realizar una comparación entre ellos, exceptuando aquellos casos donde es preciso realizar comparaciones entre mayúscula y minúscula. Esto garantizará que ambas cadenas estén a la par en el momento de realizar la comparación.

(n)En la medida de lo posible, evitar el uso de variables globales. Declarar variables locales cuando sea necesario, y pasarla como parámetro a otros métodos para evitar compartir variables. Esto permite hacerle un mejor seguimiento al valor de las variables.

(o)No programar las acciones que deben ejecutar un evento click en otros métodos. Si estas acciones son requeridas nuevamente, se debe invocar el método manejador del evento click.

(p)Evitar trabajar con rutas (direcciones) constantes. Es recomendable trabajar siempre con rutas relativas.

(q)Si son requeridos archivos de configuración para que la aplicación se ejecute, esta debe verificar la existencia de los mismos, en caso de que dichos archivos no se encuentren, la aplicación debe ser capaz de crear unos por defecto.

(r) No colocar más de una clase en un archivo simple.

(s) Evitar pasar demasiados parámetros a un método. Si se tienen que pasar más de 5 parámetros, estudiar la posibilidad si estos se pueden redefinir como una estructura o una clase.

(t) Se debe trabajar con clases que permitan el registro de errores, advertencias y movimientos realizados por el usuario, de manera que se generen reportes que sean visualizados por el administrador del sistema, ya sea por la misma aplicación o por correo electrónico.

• Interacción con Base de Datos

(a)Todas las sentencias propias del lenguaje SQL, deben se escritas en mayúscula. Ejemplo: SELECT, WHERE, INSERT, UPDATE, entre otros.

(b)Si se abren conexiones a base de datos, las mismas deben ser cerradas antes de finalizar el último bloque de instrucción. Esto garantizará que si ocurre una excepción en la apertura de la conexión, esta sea cerrada

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve14 de 24

Page 15: Estándares de Programación

satisfactoriamente al finalizar el bloque.

• Manejo de Mensajes

(a)El manejo de mensajes tanto de éxito como de error, deben ser implementados a través de configuración (XML, tabla en la base de datos). Si la tecnología lo permite, los mensajes deberían ser cargados desde la configuración en alguna estructura de datos persistente en memoria principal mientras la aplicación está funcionando u operando.

(b)Los mensajes de error deben ayudar a los usuarios a resolver los problemas que se estén presentando en la aplicación. No se deben mostrar mensajes que digan: “Error en la aplicación” o “Se ha producido un Error”. En lugar de esto, se deben dar mensajes concretos tal como: “No se ha podido actualizar la base de datos. Asegúrese de que el nombre de usuario y la contraseña sean correctos”.

(c) Cuando se muestran mensajes de error, además de indicar lo que está mal, debe decirle al usuario cómo resolver el problema presentado. En vez de mostrar un mensaje de este tipo: “No se ha podido actualizar la base de datos”, se debe mostrar uno que le de indicaciones al usuario: “No se ha podido actualizar la base de datos. Asegúrese de que el nombre de usuario y la contraseña sean correctos”.

(d)Si al cargar una aplicación, se encuentra un valor incorrecto en alguno de los archivos de configuración, se debe mostrar un mensaje de error que indique a los usuarios cuáles son los valores correctos.

(e)En la medida de lo posible, los mensajes deben ser cortos y amigables al usuario para su fácil comprensión. Para el registro real de errores en el log, se debe aportar la mayor información posible del error que se está presentando. Esto ayudará mucho en el diagnóstico de problemas.

5. Arquitectura

(a)Siempre usar arquitectura de n-capas.

(b)Nunca acceder desde las interfaces de usuario directamente a la base de datos. Siempre debe haber una capa de clases de datos que se encarga de

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve15 de 24

Page 16: Estándares de Programación

esta labor. Esto es de gran ayuda en el caso de migrar de una base de datos a otra.

(c) En la capa de datos se debe hacen capturar todas las excepciones correspondientes a la base de datos. Los datos registrados deben incluir el nombre de los comandos en ejecución, nombre de los procedimientos almacenados, parámetros, cadena de conexión utilizada, entre otros. Esto con el fin de que, en el caso que sea necesario, otra capa de la aplicación sea capaz de tomar las medidas apropiadas.

6. Programación Web

(a)Se debe evitar el uso de javaScript dentro de los archivos HTML, es preferible separarlos en un archivo (de extensión .js).

(b)Se recomienda el uso de hojas de estilo (css), se debe evitar a toda costa colocar el estilo de las páginas dentro de las etiquetas HTML. Esto ayudará a realizar cambios de apariencia en las interfaces de usuario de manera rápida.

(c) Realizar las validaciones de datos de los formularios, tanto las que se pueden hacer del lado del cliente (ejemplo: JavaScript) como las que se pueden hacer del lado del servidor (ejemplo: PHP). Del lado del cliente se deben realizar las validaciones de campos en blanco y las de caracteres o valores admitidos en los campos, de manera que queden en el servidor solo las validaciones que estrictamente se deben hacer allí. Realizar las validaciones del lado del cliente evita carga innecesaria en el servidor, y ofrece mejores tiempos de respuesta a los usuarios.

(d)No utilizar variables sesión dentro del código HTML. Estas deben ser utilizadas dentro de las clases y se deben colocar métodos que puedan acceder a los valores de las mismas.

(e)No almacenar grandes objetos en variables sesión. Esto puede consumir una gran cantidad de memoria del servidor en función del número de usuarios.

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve16 de 24

Page 17: Estándares de Programación

7. Comentarios

(a)Documentación de la Clase: Se coloca al comienzo del archivo y está compuesto por la licencia (en el caso que aplique), el nombre del autor, la fecha de creación, versión y las modificaciones realizadas con el nombre de la persona y fecha (en caso que aplique). Se debe hacer uso del estándar de documentación existente para el lenguaje en el que se está desarrollando.

(b)Implementación de la Clase: Este comentario va antes de la sentencia class, debe contener cualquier información aplicable a toda la clase (generalmente propósito y funcionalidades de la misma).

(c) De métodos/funciones: Se coloca antes de cada función o método dando una breve descripción de su funcionalidad, resaltando sus aspectos de mayor relevancia.

(d)De variables: Se coloca antes de la declaración de la misma. Este tipo de comentarios se realiza solo en casos que lo amerite.

(e)En el código: Solo se coloca antes del trozo de código que necesite una aclaración o explicación.

(f) No escribir comentarios si el código es fácilmente comprensible sin los mismos. Al hacer uso correcto de los estándares de nombrado y uso de variables y métodos, se disminuye la cantidad de comentarios en el código.

(g)Los comentarios de pocas líneas hacen el código más elegante. Sin embargo, es peor no tener comentarios en código poco legible.

8. Manejo de Excepciones

(a)Nunca hacer captura de excepción y no hacer nada. Si oculta una excepción, nunca se podrá saber si la excepción que ocurrió o no.

(b)En el caso de que ocurra alguna excepción, se debe dar un mensaje amigable al usuario, pero en el log de errores se debe contar con todos los posibles detalles sobre el error, incluyendo el momento en que ocurrió, método y nombre de clase, entre otros.

(c) No utilizar la sentencia try – catch (captura de excepciones) en todos los métodos de la clase. Se debe utilizar sólo si existe la posibilidad de que una

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve17 de 24

Page 18: Estándares de Programación

excepción específica puede ocurrir y no puede ser impedido por cualquier otro medio. Siempre se deben hacer las validaciones de datos correspondientes antes de esperar a que se produzcan excepciones. Por otra parte, siempre se debe realizar el manejo de excepciones cuando la aplicación se comunica con sistemas externos, dispositivos de hardware, entre otros. El manejo de excepciones es importante para la captura de errores y para la reparación de los mismos.

(d)No escribir bloques try – catch muy largos. De ser necesario, se debe separar en varios bloques try – catch que contengan las tareas específicas realizadas por el sistema. Esto permitirá identificar en qué trozo de código se ha producido alguna excepción y así dar un mensaje más acertado al usuario.

9. Parametrización y Configuración de una aplicación

Si el lenguaje, herramienta o “framework” en el cual se basa la aplicación no provee mecanismos por defecto para establecer configuraciones o parámetros, y nuestra aplicación necesita definirlos, se deberá utilizar XML como formato de archivos de configuración. Estos archivos deberán ubicarse en un directorio llamado “conf”, que estará ubicado en el directorio raíz de la aplicación.

10. Sobre la organización de una aplicación a nivel de Sistema de Archivos

APP

|- admin (Sección Administrativa)

|- conf (Configuración general de todos los módulos)

|- modulo_x (Nombre de la carpeta correspondiente a un módulo. Ej: Noticias)

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve18 de 24

Page 19: Estándares de Programación

|- models (Clases que encapsulan lógica de negocio y acceso a los datos)

|- views (Programas que se encargan de la presentación de la aplicación al usuario final)

|- css

|- images

|- inc

|- js

|- controlers (Programas que se encargan de gestionar las peticiones e invocar las “vistas” y “modelos” involucrados)

|- public (Sección Pública)

|- conf

|- modulo_x

|- models

|- views

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve19 de 24

Page 20: Estándares de Programación

|- css

|- images

|- inc

|- js

|- controlers

|- db (Todo lo referente a la base de datos de la aplicación, como por ejemplo Scripts SQL, procedimientos de carga de datos, entre otros)

|- lib (Librerías generales para toda la aplicación)

|- il8n (Librerías para el manejo de la internacionalización)

|- logs (Archivos de Logs de la Aplicación)

|- tests (Pruebas Unitarias)

|- docs (Documentación de toda la aplicación)

11. Sobre las Estructuras de Datos (Persistencia)

(a)Los nombres de las bases de datos deben ser lo más explícitos posibles, evitar el uso de abreviaturas, a menos que sean de uso común. Hay que mantener coherencia y consistencia en los nombres.

(b)Toda tabla debe tener una clave primaria. Deben encontrarse un conjunto

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve20 de 24

Page 21: Estándares de Programación

de datos (al menos uno) cuya combinación permita identificar unívocamente las filas de una tabla o relación.

(c) Hay que elegir con sumo cuidado el tipo de atributos de las tablas (columnas), es recomendable usar el que requiera menos espacio de almacenamiento que aplique, y en caso que se necesite aumentar su rango, se usa la instrucción ALTER TABLE para cambiar o aumentar tipo previamente elegido

(d)A la hora de seleccionar los índices, se pueden seguir las siguientes indicaciones:

• No crear índices sobre relaciones pequeñas.

• Añadir un índice sobre los atributos que se utilizan para acceder con mucha frecuencia.

• Evitar los índices sobre atributos que se modifican a menudo.

• Evitar los índices sobre atributos poco selectivos (aquellos en los que la consulta selecciona una porción significativa de la relación).

• Evitar los índices sobre atributos tipo caracteres de larga longitud.

• Los índices creados se deben documentar, explicando las razones de su elección.

• Según el manejador de Base de Datos utilizado, una clave foránea genera automáticamente un índice, si no lo hace debe crearse, para mejorar el rendimiento de las operaciones de intersección entre las tablas relacionadas (JOIN).

A continuación se presenta un cuadro con los estándares de nombres de los componentes involucrados en una base de datos:

Nombre Reglas para nombrar Ejemplos

Base de Datos Los nombres deben estar en minúscula, y en caso de ser palabras compuestas, estas se deben separar con un guión

registro_nic_db

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve21 de 24

Page 22: Estándares de Programación

bajo (“_”) , estar en singular y terminar con un db.

Tablas

Comenzar en minúscula y con la letra t si son palabras compuestas, estas se deben separar con un guión bajo (“_”) y se escriben en plural. Utilizar la letra t nos permite distinguir rápidamente las tablas entre los diferentes objetos que se almacenan en una bd.

t_personast_instituciones_legales

Columnas

Se escriben en minúscula y en singular. Si son palabras compuestas, estas se deben separar con un guión bajo (“_”). En caso que la columna sea clave (primaria o foránea) esta debe comenzar con la palabra id.

nombrenombre_profesorid_alumnoid_estado

Clave Primaria

El nombre de la restricción de la clave primaria debe comenzar con “pk”, seguida del nombre de la clave primaria. Si esta es una clave compuesta, las palabras deben separarse con un guión bajo (“_”) y deben colocarse de una manera clara y concisa.

pk_id_alumnopk_id_recurso_noticia

Clave Foránea El nombre de la restricción de fk_id_alumno

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve22 de 24

Page 23: Estándares de Programación

la clave foránea debe comenzar con “fk”, seguida del nombre de la clave foránea. Si esta es una clave compuesta, las palabras deben separarse con un guión bajo (“_”) y deben colocarse de una manera clara y concisa.

fk_id_recurso_noticia

Índices

El nombre de la restricción del índice debe comenzar por ix, seguida del nombre de la tabla y del nombre sobre el cual se crea el índice.

ix_t_alumno_id_alumnoix_t_alumno_id_recurso_noticia

12. Sobre la Seguridad

La seguridad de una aplicación, especialmente en un ambiente de red, involucra aspectos que van más allá de la misma, como el uso de protocolos de cifrado, “firewalls”, configuración de servidores web, sistema operativo, robustez o madurez del lenguaje de programación, entre otros. Sin embargo, existen algunos aspectos propios de la forma de programación que deben tomarse en cuenta:

(a)Todas las páginas de uso administrativo deben ser referenciadas por otra (puede ser ella misma). En otras palabras, si a un programa “C” se llega solo desde los programas “A” y “B”, el programa “C” debe controlar esto. En ambientes web, esto se debe realizar utilizando el encabezado http: referer.

(b)Validar los campos del formulario de manera adecuada para evitar técnicas de ataque como “SQL injection”, como por ejemplo los caracteres “ ' ” y “ --

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve23 de 24

Page 24: Estándares de Programación

”.

(c) Estar atentos al “cross site scripting (XSS)”, validando los campos adecuadamente escapando caracteres especiales usados comúnmente en HTML, tales como: “<”, “>”, “&”,“#”, entre otros.

(d)Evitar en los formularios el pase de parámetros por el método GET.

(e)Evitar pasar a través de un formulario información sensible por medio de parámetros ocultos (hidden).

(f) Usar SSL en caso que lo amerite.

(g)No colocar en el “QUERY STRING” datos de alta importancia (por ejemplo la clave del usuario), y de ser necesario por lo menos encriptarlos.

Estándares de Programación Versión: 0.0.1

Elaborado por: Danela Gutiérrez Revisado por: Carmen Pereira Aprobado por: Francelis Konrad

Av. Universidad, Esquina El Chorro, Torre MCT (antigua sede de Banesco), piso 12, La Hoyada, CaracasTelf. 0212-7718800. Fax 0212-771.86.48

Sitio Web: www.cnti.gob.ve24 de 24