Un estándar de codificación completo comprende todos los aspectos de la generación de código. Si bien los programadores deben implementar un estándar de forma prudente, éste debe tender siempre a lo práctico. Un código fuente completo debe reflejar un estilo armonioso, como si un único programador hubiera escrito todo el código de una sola vez. Al comenzar un proyecto de software, es necesario establecer un estándar de codificación para asegurarse de que todos los programadores del proyecto trabajen de forma coordinada. Cuando el proyecto de software incorpore código fuente previo, o bien cuando realice el mantenimiento de un sistema de software creado anteriormente, el estándar de codificación debería establecer cómo operar con la base de código existente.

La legibilidad del código fuente repercute directamente en lo bien que un programador comprende un sistema de software. La mantenibilidad del código es la facilidad con que el sistema de software puede modificarse para añadirle nuevas características, modificar las ya existentes, depurar errores, o mejorar el rendimiento. Aunque la legibilidad y la mantenibilidad son el resultado de muchos factores, una faceta del desarrollo de software en la que todos los programadores influyen especialmente es en la técnica de codificación. El mejor método para asegurarse de que un equipo de programadores mantenga un código de calidad es establecer un estándar de codificación sobre el que se efectuarán luego revisiones del código de rutinas.

Usar técnicas de codificación sólidas y realizar buenas prácticas de programación con vistas a generar un código de alta calidad es de gran importancia para la calidad del software y para obtener un buen rendimiento. Además, si se aplica de forma continuada un estándar de codificación bien definido, se utilizan técnicas de programación apropiadas, y, posteriormente, se efectúan revisiones del código de rutinas, caben muchas posibilidades de que un proyecto de software se convierta en un sistema de software fácil de comprender y de mantener.

Aunque el propósito principal para llevar a cabo revisiones del código a lo largo de todo el desarrollo es localizar defectos en el mismo, las revisiones también pueden afianzar los estándares de codificación de manera uniforme. La adopción de un estándar de codificación sólo es viable si se sigue desde el principio hasta el final del proyecto de software. No es práctico, ni prudente, imponer un estándar de codificación una vez iniciado el trabajo

Las técnicas de codificación incorporan muchos aspectos del desarrollo del software. Aunque generalmente no afectan a la funcionalidad de la aplicación, sí contribuyen a una mejor compresión del código fuente. En esta fase se tienen en cuenta todos los tipos de código fuente, incluidos los lenguajes de programación, de marcado o de consulta.

En general una técnica de codificación no pretende formar un conjunto inflexible de estándares de codificación. Más bien intenta servir de guía en el desarrollo de un estándar de codificación para un proyecto específico de software.

 

GENERALES

Ø      Para conservar recursossea muy selectivo en la elección del tipo de dato, asegúrese que el tamaño de una variable no sea excesivamente grande. Por ejemplo en los ciclos for es mejor, en la mayoría de las veces utilizar un tipo de dato tipo short que int.

Ø      Mantenga el tiempo de vida de las variables tan corto como sea posible,esto es muy importante por ejemplo cuando se utiliza un recurso finito como una conexión a una Base de Datos.

Ø      Mantenga el scope de las variables tan corto como sea posible, esto sirve para evitar confusiones, mejorar la mantenibilidad y además minimiza la dependencia, es decir si por algún motivo se comete el error de borrar una variable es más fácil de encontrar el error si esta tiene un scope más pequeño.

Ø      Use los procedimientos y variables con un solo propósito. Evite crear procedimientos multipropósito que lleven a cabo una variedad de funciones no relacionadas.

Ø      Dentro de una clase, evite el uso de variables publicas, en cambio utilice procedimientos y propiedades que accedan a dichas variables (privadas), así provee una capa de encapsulación y brinda la posibilidad de validar valores de cambio sobre las mismas, antes de manipularlas directamente.

Ø      Cuando utilice objetos pooled de MTS (Microsoft Transaction Server), adquiera los recursos lo mas tarde posible y libérelos lo mas prontocomo sea posible, esto repercute en el manejo de recursos

Ø      Use siempre un esquema transaccional como MTS o SQL Server y minimice el scope y la duración de las transacciones.

Ø      Cuando se trabaje en un entorno web distribuido (aldea web), tenga cuidado de almacenar información en variables de sesión ASP ya que el estado de sesión es almacenado siempre en una sola maquina, considere mejor almacenar dicha información en una base de datos.

Ø      No abra conexiones a datos usando credenciales especificas de usuario, ya que estas no podrán ser reutilizadas por el pool de conexiones.

Ø      Evite el uso de conversión de tipos o casting ya que esto puede generar resultados imprevistos, sobre todo cuando dos variable están involucradas en una sentencia, utilice el cast solo en situaciones triviales, cuando este no sea el caso asegure de comentar la razón por la cual lo hizo.

Ø      Use siempre rutinas de manejo de excepciones

Ø      Sea especifico cuando declare objetos que puedan generar colisión, por ejemplo si tiene dos métodos con el mismo nombre en diferentes namespaces escríbalos con el nombre completo incluyendo el del paquete.

Ø      Evite el uso de variables en el ámbito de aplicación (web).

Ø      Use siempre sentencias Select-Case o Switch en lugar de utilizar sentencias if-then repetitivas.

Ø      Libere explícitamente las referencias a objeto. (variable = nothing ó variable = null)

Ø      Siempre que sea posible utilice polimorfismo en vez de cláusulas Switch o Select.

 

Las técnicas de codificación están divididas en tres secciones:

Ø      Nombrado

Ø      Documentación Interna (Comentarios)

Ø      Formato

 

NOMBRADO

El esquema de nombres es una de las ayudas más importantes para entender el flujo lógico de una aplicación. Un nombre debe más bien expresar el "qué" que el "cómo". Si se utiliza un nombre que evite referirse a la implementación se estará conservando la abstracción de la estructura ya que la implementación está sujeta a cambios, de esta manera se describe que hace la estructura y no como lo hace.

Por ejemplo es mas claro nombrar un procedimiento de acceso a datos SeleccionarRegistro() que RealizarConsultaSelect(), porque lo que importa (para que otra persona entienda el código) es que se supone que hace el método y no como lo hace.

Otra directiva es la de utilizar nombres tan largos como para que se entiendan pero a la vez tan cortos como para que no den información irrelevante, por ejemplo es mejor emplearSeleccionarComida() que SeleccionarlaComidadelMenu().

Desde el punto de vista de la programación, un nombre único sirve solamente para diferenciar un elemento de otro. Los nombres expresivos funcionan como ayuda para el lector, por eso, es lógico dar nombres que sean fáciles de comprender. No obstante, asegúrese de que los nombres escogidos sean compatibles con las reglas de cada lenguaje y con los estándares.

 

Estructuras (namespaces, procedimientos, clases, interfaces y propiedades)

 

Ø      Los nombres de todas las estructuras de código deben ser en español.

Ø      Los namespaces deben empezar por el nombre de la compañía seguido de la unidad de negocio, el producto o proyecto yla funcionalidad:

Heinsohn.FabricaSw.Papelsa.AccesoaDatos

[compañía].[unidad de negocio].[proyecto].[funcionalidad]

 

Ø      El nombre del ensamblado y el namespace root deben ser idénticos

Ø      El nombre de la clase y el archivo fuente deben ser iguales.

Ø      No se debe usar la notación húngara, la cual prefija una abreviatura referente al tipo de objeto: lblAceptar (label), btnOK(Botón), etc.

Ø      Evite nombres imprecisos que permitan interpretaciones subjetivas, como por ejemplo DefinirEsto(), o bien ytG8 para una variable. Tales nombres contribuyen más a la ambigüedad que a la abstracción.

Ø      En la POO es redundante incluir nombres de clases en el nombre de las propiedades de clases, como por ejemplo Rectángulo.RectánguloArea, en su lugar, utilice Rectángulo.Area, pues el nombre de la clase ya contiene dicha información.

Ø      Utilice la técnica verbo-sustantivo para nombrar procedimientos que ejecuten alguna operación en un determinado objeto, como por ejemplo CalcularDesperdicio().

Ø      Empiece los nombres de clase y propiedades con un nombre, por ejemplo CuentaBancaria, la primera letra de cada palabra debe ser mayúscula.

Ø      En lenguajes que permitan sobrecarga de funciones, todas las sobrecargas deberían llevar a cabo una función similar. Para los lenguajes que no permitan la sobrecarga de funciones, establezca una nomenclatura estándar relacionada con funciones similares.

Ø      Empiece los nombres de interfaz con el prefijo "I", seguido de un nombre o una frase nominal, como IComponente, o con un adjetivo que describa el comportamiento de la interfaz, como IPersistible. No utilice el subrayado“_”(con la excepción de las variables privadas), y utilice lo menos posible las abreviaturas, ya que pueden causar confusiones.

 

Variables

Ø      Las variables miembro se escriben con la primera letra de cada palabra en mayúscula a excepción de las variable miembro privadas. Las Variables internas o de bloque deben ir en minúscula. En el caso de las variablesmiembro privadas, se debe utilizar el prefijo “m_” sumado al nombre de la variable (m_variable).

Ø      Es recomendado que las variable booleanas contengan una palabra que describa su estado: puedeEliminarse, esGrande, tieneHijos, etc. Y siempre se debe referir al estado verdadero: tieneCredito en cambio de noTieneCredito

Ø      Incluso para el caso de una variable de poco uso, que deba aparecer sólo en unas cuantas líneas de código, emplee un nombre descriptivo. Utilice nombres de variables de una sola letra, como i o j sólo para índices (ciclos for).

Ø      No utilice números o cadenas literales, como por ejemplo For i = 1 To 7. En su lugar, emplee constantes con nombre, del tipo For i = 1 To Enumeracion.length para que resulten fáciles de mantener y comprender.

 

Parámetros

Los parámetros siguen el mismo estándar de las variables

 

Tablas

Ø      Cuando ponga nombres a tablas, hágalo en singular. Por ejemplo, use Empleado en lugar de Empleados.

Ø      Cuando ponga nombre a las columnas de las tablas, no repita el nombre de la tabla; por ejemplo, evite un campo llamado EstudianteApellido de una tabla llamada Estudiante. (Igual que con las propiedades de una clase).

Ø      No incorpore el tipo de datos en el nombre de una columna.

 

Microsoft SQL Server

Ø      No ponga prefijos sp a los procedimientos almacenados, ya que se trata de un prefijo reservado para la identificación de procedimientos almacenados de sistemas.

Ø      No ponga prefijos fn_ a las funciones definidas por el usuario, ya que se trata de un prefijo reservado para funciones integradas.

Ø      No ponga prefijos xp_ a los procedimientos almacenados extendidos, ya que se trata de un prefijo reservado para la identificación de procedimientos almacenados extendidos.

Ø      Los nombres de los campos deben empezar por Mayúscula.

 

Varios

Ø      Para términos largos o utilizados con frecuencia, utilice abreviaturas para mantener las longitudes de los nombres dentro un límite razonable, por ejemplo, "HTML" en lugar de "Lenguaje de marcado de hipertexto". En general, los nombres de variable con más de 32 caracteres son difíciles de leer. Además, asegúrese de que sus abreviaturas sean coherentes a lo largo de toda la aplicación. Si utiliza indistinta y aleatoriamente "HTML" y "Lenguaje de marcado de hipertexto" en un mismo proyecto, provocará confusión.

Ø      Minimice el uso de abreviaturas; pero si las emplea, use coherentemente las que haya creado. Una abreviatura sólo debe tener un significado y, del mismo modo, a cada palabra abreviada sólo debe corresponder una abreviatura. Por ejemplo, si utiliza "min." para abreviar "mínimo", hágalo siempre así, y no use también "min." para abreviar "minuto".

Ø      Cuando nombre un procedimiento que retorne un valor, incluya además de la acción, la entidad que será devuelta; LeerArchivo, ConsultarSaldo, ObtenerResumen.

Ø      Los archivos y los nombres de carpetas, al igual que los nombres de procedimientos, deben describir claramente su finalidad.

Ø      Evite reutilizar nombres para elementos diferentes, como por ejemplo una rutina llamada ProcesoLavado() y una variable iLavado.

Ø      Evite el uso de caracteres como $ o %

Ø      No use nombres que sean dependientes del tipo de variable, control o clase en cambio utilice, como ya se dijo, nombres que describan el propósito de la variable , control o propiedad.

Ø      Evite este comportamiento: void Escribir(double doubleValor), en su lugar utilice void Escribir(double valor).

 

COMENTARIOS

Existen dos tipos de documentación de software: externa e interna. La documentación externa, como por ejemplo las especificaciones, los archivos de ayuda y los documentos de diseño, se debe mantener fuera del código fuente. La documentación interna está formada por los comentarios que los programadores escriben dentro del código fuente durante la fase de desarrollo.

Uno de los problemas de la documentación de software interna es garantizar que se mantengan y actualicen los comentarios al mismo tiempo que el código fuente. Aunque unos buenos comentarios en el código fuente no tienen ningún valor en el tiempo de ejecución, resultan valiosísimos para un programador que tenga que mantener una parte de software particularmente compleja.

 

Siga las siguientes pautas para realizar comentarios:

Ø      Los comentarios deben ser en español.

Ø      Si programa en C#, utilice la función de documentación XML. Cuando modifique el código, mantenga siempre actualizados los comentarios circundantes.

Ø      Al principio de cada rutina, resulta útil hacer comentarios estándar, repetitivos, que indiquen el propósito de la rutina, las suposiciones y las limitaciones. Un comentario repetitivo podría consistir en una breve introducción que explicara por qué existe y qué puede hacer.

Ø      Evite añadir comentarios al final de una línea de código, porque lo hacen más difícil de leer. Sin embargo, los comentarios de final de línea sí son apropiados al anotar declaraciones de variables. En este caso, alinee todos los comentarios de final de línea en la misma posición de tabulación.

Ø      Evite los comentarios recargados, como las líneas enteras de asteriscos. En su lugar, utilice espacios para separar los comentarios y el código.

Ø      Evite rodear un bloque de comentarios con un marco tipográfico. Puede resultar agradable, pero es difícil de mantener.

Ø      Antes de la implementación, quite todos los comentarios temporales o innecesarios, para evitar cualquier confusión en la futura fase de mantenimiento.

Ø      Si necesita realizar comentarios para explicar una sección de código compleja, examine el código para decidir si debería volver a escribirlo. Siempre que sea posible, no documente un código malo, vuelva a escribirlo. Aunque, por regla general, no debe sacrificarse el rendimiento para hacer un código más simple para el usuario, es indispensable un equilibrio entre rendimiento y mantenibilidad.

Ø      Use frases completas cuando escriba comentarios. Los comentarios deben aclarar el código, no añadirle ambigüedad.

Ø      Vaya comentando al mismo tiempo que programa, porque probablemente no tenga tiempo de hacerlo más tarde. Por otro lado, aunque tuviera oportunidad de revisar el código que ha escrito, lo que parece obvio hoy es posible que seis semanas después no lo sea.

Ø      Evite comentarios superfluos o inapropiados, como comentarios divertidos al margen.

Ø      Use los comentarios para explicar el propósito del código. No los use como si fueran traducciones literales.

Ø      Para evitar problemas recurrentes, haga siempre comentarios al depurar errores y solucionar problemas de codificación, especialmente cuando trabaje en equipo.

Ø      Haga comentarios en el código que esté formado por bucles o bifurcaciones lógicas. Se trata en estos casos de áreas clave que ayudarán a los lectores del código fuente.

Ø      Realice los comentarios en un estilo uniforme, respetando una puntuación y estructura coherentes a lo largo de toda la aplicación.

Ø      Separe los comentarios de sus delimitadores mediante espacios. Si respeta estas normas, los comentarios serán más claros y fáciles de localizar si trabaja sin indicaciones de color.

Ø      Cada declaración de variable importante debe incluir un comentario en la misma línea que describa el uso de la variable que se declara.

Ø      Después de la secuencia de continuación de línea no puede escribirse un comentario en la misma línea.

Ø      Todos los comentarios deben estar ortográficamente bien escritos, una escritura incorrecta demuestra un desarrollo negligente.

Ø      Evite comentarios que expliquen cosas obvias, en la mayoría de las cosas el código debe ser autoexplicativo. Un buen código con buenas prácticas de nombrado no debe ser comentado.

 

FORMATO

El formato hace que la organización lógica del código sea más clara. Si toma el tiempo de comprobar que el código fuente posee un formato coherente y lógico, les resultará de gran utilidad a usted y a otros programadores que tengan que descifrarlo.

Siga las siguientes pautas para establecer el formato:

Ø      Evite albergarmúltiples clases en un solo archivo.

Ø      Establezca un tamaño estándar de sangría (por ejemplo, cuatro espacios o una tabulación) y úselo siempre. Alinee las secciones de código mediante la sangría predeterminada.

Ø      Use un único tipo de letra cuando publique versiones impresas del código fuente.

Ø      Declare una sola variable por línea (excepto VB).

Ø      Incluya llaves en las bloques condicionales así sea de una sola sentencia (excepto VB).

Ø      Agregue los namespaces en orden descendente empezando por los del sistema y terminado por los personalizados o de usuario.

Ø      Una clase debe estar definida en orden descendente de la siguiente manera: Variables Miembro, Constructores, Enumeraciones, Estructuras o Clases anidadas,Propiedades y por ultimo los Métodos.

Ø      La secuencia de declaración de acuerdo a los modificadores de acceso debe ser la siguiente:

     public

     protected

     internal

     private

Ø      Aísle la interfaz de implementación utilizando bloques Region.

Ø      Alinee verticalmente las llaves de apertura y cierre de cualquier bloque:

Public void Main()

{

...

}

Ø      Establezca una longitud de línea máxima para el código.

Ø      Utilice espacios antes y después de los operadores siempre que eso no altere la sangría aplicada al código:

miVariable = 3; en vez de miVariable=3;

Ø      Use espacios en blanco para organizar a su antojo secciones de código. De tal manera que se comprenda la segmentación del código. En casos donde lo amerite utilice regiones.

Ø      Cuando tenga que dividir una línea en varias, aclare que el código sigue en la línea de más abajo mediante un operador de concatenación colocado al final de cada línea, y no al principio.

Ø      Siempre que sea posible, no coloque más de una instrucción por línea, a excepción de los bucles.

Ø      Al escribir en HTML, establezca un formato estándar para las etiquetas y los atributos; como por ejemplo, las etiquetas siempre en mayúscula y los atributos en minúscula

Ø      Cuando escriba instrucciones SQL utilice mayúsculas para las palabras clave: SELECT, UPDATE, WHERE, FROM, etc.

Ø      Coloque las cláusulas SQL principales en líneas separadas, de modo que las instrucciones sean más fáciles de leer y editar:

SELECT Nombre, Apellido

FROM Clientes

WHERE Fecha= ‘Now.Today’;

Ø      Cuando aplique mas de un atributo a una estructura colóquelos individualmente en una línea y no todos juntos y separados por comas.

Ø      Siempre que sea posible inicialice las variables en el momento de la declaración (no es necesario en VB).

Ø      Siempre utilice los tipos nativos de cada lenguaje y no los del CTS.

Ø      Evite hacer unboxing y boxing secuencialmente, es decir en la misma rutina.

Ø      No compare strings con “” o con string.empty, use la propiedad length del string:

If(String.length == 0)

Ø      Evite llamadas a métodos dentro de sentencias condicionales.

Ø      Evite utilizar recursividad, use mejor ciclos for anidados.

Ø      Use el operador condicional ternario solo en casos triviales, cuando sean casos complejos evítelo.

Evite comparar variables booleanas contra false o true, en vez de eso utilice el operador de negación:

If(puedeEliminarse == true)if(puedeEliminarse=false)

Mejor use

If(puedeEliminarse)f(!puedeEliminarse)

 

ADICIONALES

 

Evite referencias mutuas entre dos ensamblados.

Nunca omita los modificadores de acceso, declárelo siempre explícitamente.

Para el control de Código Fuente se debe utilizar Visual Source Safe.

Para desplegar mensajes de error se debe usar los errores personalizados utilizando ASP web Pages. También podemos utilizar MessageBox con JavaScript.

Las excepciones se deben capturarsiempre en el nivel mas alto del sistema, es decir en la capa de mas abstracción, por lo general es la capa de interfaz de usuario. Es una directiva general evitar en todo caso crear excepciones personalizadas, pero en el caso de que sea necesario siga estas premisas:

 

Ø      Se deben manejaren clases aparte y se debe heredar de la clase ApplicationException.

Ø      Se debe sobrescribir el método ToString().

Ø      Implemente el patrón de diseño de las excepciones, sobrescribiendo estos 3 métodos :

public MiExcepcion()

public MiExcepcion(string message)

public MiExcepcion(string message, Exception innerException)

 

Ø      Nunca declare una sentencia catch vacía.

Ø      Evite anidar bloques try/catch.

Ø      Ordene la captura de excepciones (catch) siempre en orden descendente desde la más particular hasta la más genérica.

Ø      Evite relanzar una excepción, permita mejor que vaya ascendiendo y que sea capturada en la capa superior.Si relanza una excepción omita la referencia:

Try

{

....

}

catch (Exception e)

{

throw (no use throw e)

}

 

Ø      Use los bloquefinally solo para realizar funciones de limpieza y liberación de recursos.

Ø      Siempre que sea posible prefiera la validación al manejo de excepciones:

Try

{

conexión.Close()

}

catch (Exception a)

{

... Manejo de excepción

}

 

cámbielo por:

if(conexión.State() != Conecction.State.Closed )

{

con.Close();

}