Mejores Practicas de Programación II: Normas de Codificación y Convenciones de Nomenclatura

Normas de Codificación y Convenciones de Nomenclatura.

Continuamos con más consejos, ahora toca mencionar el tema de las normas  de codificación y convenciones de nomenclaturas para tener establecidos en un proyecto, ya que es importante que todo el proyecto se encuentre bien estructurado y todo bajo unas normas establecidas desde un inicio. Esto ayudara para que nuevos programadores cuando entren a un proyecto avanzado les sea más fácil encontrar métodos, conocer los parámetros y sobre todo la nomenclatura dentro del proyecto, sin mencionar que facilitara la documentación.

.Net

Usar la convención de PascalCasing inclusive en acrónimos como Html. Utilizarlo en todos los miembros públicos, tipos y nombres de namespace que contengan varias palabras.

Usar camelCase para variables locales y argumentos de métodos, es decir que siempre la primera letra será minúscula.

public class UserLog

{

public void Add(LogEvent logEvent)

{

int itemCount = logEvent.Items.Count;

// ...

}

}

 

Alinear siempre las llaves verticalmente, para una mejor lectura de código y siempre usar el PascalCasing en cada salto de línea.

Declarar todas las variables al inicio de una clase, esto con el fin de evitar rebuscar la definición de las variables en el código.

Convención de diseño:

• Realizar una declaración por línea.

• Usar paréntesis cuando se genera una cláusula en una expresión.

If ((val1 > val2) && (val1 > val3) )

{

// Acción.

}

• Hacer uso de espacios con el tabulador y no con espacios, esto facilitara la lectura del código.

public class ClientActivity

{

public void ClearStatistics()

{

//...

}

public void CalculateStatistics()

{

//...

}

}

Convención de Comentarios:

• Colocar el comentario arriba de algún método o clase y no entre las líneas de código.
• Utilizar la etiqueta
  para agregar el bloque de comentarios.
• Usar la etiqueta para una descripción detallada o resaltar como alerta sobre un objeto o método.
• Usar para describir un parámetro en específico en un método.
• Utilizar la etiqueta para describir alguna excepción que podría ejecutarse por un método.
• Iniciar el comentario con la primera letra en mayúscula.
• Terminar la línea de comentario con un punto.
• Dejar un espacio en blanco entre el limitador de comentario (//) y el texto.
  // Esto es un comentario.

 

Variables locales implícitas:

• Utilizar var para la declaración de variables locales cuando el tipo de variable es obvio, porque elimina el desorden y vuelve las variables genéricas para una fácil lectura.

Arreglos:

Usar una sintaxis concisa cuando se declara un arreglo.

// Sintaxis preferente.

String[] arreglo1 = {“a”, “e”, “i”, “o”, “u”};

// Usando var para el arreglo.

Var arreglo2 = new string[] {“a”, “e”, “i”, “o”, “u”};

// Si se especifica el tamaño del arreglo, se deberá de inicializar cada elemento por una línea

// Separada.

Var arreglo3 = new string[5];

Arreglo3[0] = “a”;

Arreglo3[0] = “e”;

Nombre de Namespace:

• El nombre del namespace deberá de ser suficientemente claro para la lectura del código y rápidamente conocer el contenido de este.
  .(|)[.][._{]
  Por ejemplo: MiProyecto.Seguridad.}
• Hacer uso del PascalCasing en el nombre del namespace.
• No utilizar el mismo nombre de una clase como un nombre de namespace dentro de este mismo.
• Organizar los namespace con una estructura claramente definida, si el nombre de estos llegan a ser demasiado largos para una sola línea se pueden romper con un punto (.)
  var currentPerformanceCounterCategory = new System.Diagnostics.
       PerformanceCounterCategory();
• Se deberá respetar el nombre del Namespace con el nombre de su propio proyecto.

 

Nombre de Clases, Estructuras e Interfaces:

• Los Nombres de las clases y estructuras deberán de ser sustantivos usando PascalCasing; por el cual se distinguen de los métodos, los cuales estos usan frases verbales.
• Nombre las interfaces con adjetivos u ocasionalmente con sustantivos.
• En las interfaces utilizar como letra iniciar I:
  Public interface IForma
  {
      ...
  }
  Public interface IColeccionForma
  {
      ...
  }
• Asegurarse de que los nombres difieran solo por el prefijo “I” en el nombre de una interfaz cuando defina un par de clases – interfaz donde la clase sea una implementación estándar de la interfaz.

Nombres de Enumeración:

Para nombre los enums se deberá de seguir la misma nomenclatura de PascalCasing, sin embargo existen pautas adicionales que se aplican a ciertas especificaciones:

• Los nombres deben ser en singular.
• Se pueden nombrar en plural solo si los valores de los campos son en bits.

Nombres de Métodos: Nombrar a cada método con verbos o frases verbales.

Nombre de Eventos:

• Los Eventos al igual que los métodos, se nombran con verbos, la diferencia es en el tiempo verbal del nombre el cual indica el momento en que se ejecuta el evento.
• Usar dos parámetros llamados “sender” y “e” en los eventos “event handlers”.
       El parámetro “sender” representa un objeto que se genera a partir del evento ejecutado.
• Nombrar las clases de los argumentos del evento con el sufijo “EventArgs”.

 

Nombre de Parámetros:

• Utilizar camelCasing en el nombre de todos los parámetros.
• El nombre del parámetro debe de ser descriptivo.

Nombre de Recursos:

• Usar PascalCasing.
• Usar solo caracteres alfanuméricos y guiones bajos para nombrar  recursos.
• En las excepciones especificar que es una.
  ArgumentoExcepcionNombreInvalido.

Escoger entre una clase y una estructura:

Lo que diferencia de una clase con una estructura es que la clase son tipos de referencia mientras que una estructura es por tipo de valor. Lo habitual sería solo usar una estructura para realizar alguna optimización, generar una estructura de datos pequeña que contenga datos que no se prevén modificar después de haber creado la estructura.

Diseño de Enum:

Existen dos tipos de enums: los simples y los indicadores (denominados flag enums).

Los simples representan pequeños conjuntos, por ejemplo una colección de colores.

Los flag enums están diseñados para un soporte de operaciones de bit a bit, por ejemplo una lista de opciones.

• Usar una enumeración (enum) para escribir parámetros, propiedades y valores de retorno que representen conjuntos de valores.

Lanzamiento de excepciones:

• Nunca devolver el código del error.
• Reportar todos los fallos por medio de una excepción.
• Encapsular la excepción original en la propiedad InnerException de un ApplicationException.

Objetos:

• Los nombres de los objetos nunca deben de iniciar con un guion bajo.