Guías técnicas Grupo Danysoft:

Reglas para codificación en C#

Leonardo Diez

Equipo Grupo Danysoft septiembre de 2003 - (902) 123146

www.danysoft.com

Este documento se ha realizado utilizando Doc-To-Help®, distribuido por :

Danysoft Internacional Avda de España 17 28100 Alcobendas – Madrid Tfno. 902.123146 Fax. 902.123145 http://www.danysoft.com http://www.danyshop.com [email protected]

www.danysoft.com - Página 2/13

Guías Técnicas Grupo Danysoft: Reglas para codificación en C#

Reglas para codificación en C# 1. Introducción La plataforma .NET ofrece numerosas ventajas a la hora de desarrollar aplicaciones. Entre otras cosas, permite que el código generado sea mucho más claro y fácil de mantener. Sin embargo, para alcanzar este objetivo es necesario establecer reglas que definan un formato común para todo el código que generamos. Esto permitirá compartir código entre los desarrolladores sin implicar costes adicionales. Dado que son muchos los que hoy día comienzan a desarrollar nuevos productos con C# o VB.NET, os brindamos de forma gratuita este documento, que evitará dedicar tiempo a crear algo que seguramente ya alguien ha tenido que hacer. Esta guía es una base que puede ser utilizada tal como está, modificada según las preferencias de los programadores que vayan a utilizarla o extendida con nuevas reglas; lo importante es que sea respetada por todos los miembros del equipo de desarrollo que la utilice. El hecho de utilizar esta guía tampoco garantiza una total independencia del código de su creador; es importante complementar su uso con la correspondiente documentación.

2. Organización de los ficheros a) Ficheros de código fuente -

Mantener las clases y los ficheros cortos, con no más de 2.000 líneas de código y que estén claramente divididas en estructuras. Crear un fichero para cada clase, con el nombre de la clase como nombre del fichero y la extensión correspondiente. Esta regla puede ser ignorada en los casos en que una clase sea muy dependiente de otra, en cuyo caso podría ser definida en el fichero de la clase importante, o incluso como una clase interna de aquélla.

b) Estructura de directorios -

Crear un directorio para cada nombre de espacio. No utilizar puntos en el nombre de los directorios. Esto hará más fácil la asociación entre directorios y espacios de nombres. Ejemplo: usar MiEmpresa/MiProyecto/CapaDatos para el espacio de nombres MiEmpresa.MiProyecto.CapaDatos, y no MiEmpresa/MiProyecto.CapaDatos.

3. Indentación a) Espacios en blanco -

Utilizar Tab para indentar el código. Nunca utilizar espacios.

www.danysoft.com - Página 3/13

b) Ajuste de línea -

Cuando una expresión no quepa en una sola línea de código, dividirla de acuerdo a estos principios: o o o o

Nueva línea después de una coma. Nueva línea después de un operador aritmético. Buscar operadores con la prioridad más alta posible. Alinear la nueva línea con el comienzo de la sección en la que se encuentra el código.

Ejemplos: - Luego de una coma: llamadaLarga(expr1, expr2, expr3, expr4, expr5);

- Luego de un operador aritmético: var = a * b / (c - g + f) + 4 * z;

- Evitar esto: var = a * b / (c - g + f) + 4 * z;

Evitar el último caso, ya que la división ocurre dentro del paréntesis y esto puede dar lugar a confusión. -

Para mantener las líneas alineadas usar Tab y complementar con espacios. Este es el único caso donde se permite el uso de espacios para indentar.

4. Comentarios a) Comentarios de bloque -

Los comentarios de bloque deben ser evitados. Para descripciones de clases y sus miembros, utilice los comentarios con /// para generar documentación. Si en algún caso se deben utilizar, use el siguiente formato: /* Línea 1 * Línea 2 * Línea 3 */

Este formato hace que el bloque sea más legible. Igualmente, los comentarios de bloque raramente son útiles. Básicamente, la utilidad que tienen es que permiten comentar temporalmente grandes bloques de código.

b) Comentarios de línea -

Los comentarios de línea se utilizan para explicar línea a línea el código fuente. También se utilizan para comentar líneas de código temporalmente. Estos comentarios deben tener el mismo nivel de indentación que el código que describen.

www.danysoft.com - Página 4/13

Guías Técnicas Grupo Danysoft: Reglas para codificación en C#

-

La longitud de un comentario no debe exceder la del código que explica. Si esto ocurre, probablemente el código es demasiado complejo, lo que implica un riesgo de errores.

c) Comentarios de documentación -

-

En la plataforma .NET, Microsoft ha introducido un sistema de generación de documentación basado en comentarios XML. Se deben utilizar comentarios de C# con etiquetas XML internas, y seguir las siguientes directivas: o Las líneas deben ser precedidas por tres barras para ser aceptadas como comentarios XML. o Las etiquetas pueden ser de dos tipos: § Elementos de documentación: Etiquetas como , o . Estas se relacionan con los elementos de la API del programa que se documenta. Estas etiquetas suelen tener atributos como name o cref, que son revisados por el compilador, por lo que deben tener valores válidos. § Formato / referencia: Etiquetas como , o . Estas permiten definir el formato que la documentación debe tener, o crear referencias a elementos del código. Ejemplo sencillo: /// /// Esta clase es la responsable de ... ///

-

Ejemplo de varias líneas: /// /// /// ///