Con un poco de estilo

Un aspecto que aunque no lo parezca es importante a la hora de programar aplicaciones es el estilo. Aunque los comentarios y todas esas cosas se suelen dejar para el final, no debería ser así por dos motivos:
Si hay que andar modificando código es más difícil encontrarlo y saber que hace cada cosa.
Al final, por mucho que digamos, "pasamos" de estar comentando y retocando el código.
Por eso he considerado importante documentarme un poco sobre el código antes de escribir una línea del mismo. Aquí van, a modo de resumen o que he considerado más importante:
1. Nombres de clases, métodos, objetos ...

• Escribir los nombres de forma que se sepa que hacen. Por ejemplo, si queremos hacer un método que calcule un área, será siempre mejor  llamarle CalcularArea() que no Calcular o Area a secas.
• Seguir una notación concreta. Yo he optado por usar una notación Pascal, que entre otras cosas consiste en poner en mayúscula las primera letra de cada palabra. Por ejemplo, podemos escribir un método de varias formas: CalcularArea(), calcular_area(), calculararea(). Cada uno es libre de escoger la que quiera, lo que si aconsejo es si escoges una, seguir siempre con esa. ¿Por qué? Pues más que nada por sencillez. Si declaro un método llamado CalcularArea() y otro calcular_superficie() cuando quiera definirlos o llamarlos no me acordare si después de Calcular iba Area o _area o que iba.
• Aplicar la misma notación a todos los objetos, nombres… Por ejemplo, si creo un objeto DataTable, sería lógico que se llamase dtClientes, por ejemplo o si creo un objeto de tipo TextBox, podría llamarse txtEliminar. Otra opción es poner “obj” delante, o incluso o (oDataTable). Otra vez lo mismo, decidas lo que decidas, seguir siempre la misma notación.

2. Orden en el código.

• Seguir un orden. En tu archivo de código usar siempre el mismo órden. El aconsejable y que tengo intención de usar yo es el siguiente:
  
  
  
  1. Instrucciones using
  2. Namespace que corresponda
  3. Clase: declaracion
  4. Variables o Campos
  5. Delegados y Eventos
  6. Propiedades
  7. Métodos, entre los que se incluye en constructor, los métodos públicos, los métodos protegidos y los métodos privados, en ese orden.
  
  
  
  
• Usar las etiquetas de región #region y #endregion para separar cada parte, de forma que lo podamos contraer o expandir según nos interese.

3. Comentarios de líneas con // y /* */

• Poner comentarios donde corresponda. No hace falta explicar al detalle todo, sino simplemente describir un poco lo que hace o aclarar cosas, sobre todo en partes de código que parezcan más confusas.
• Poner los comentarios antes de lo que se quiere comentar y en una línea nueva, salvo en casos de pequeños comentarios, que se pueden poner seguido.

4. Comentarios XML
En Visual Studio es posible comentar las clases, métodos, campos, etc. mediante etiquetas XML. Aunque en principio puede parecer menos útil que los comentarios //, tiene algunas ventajas, como por ejemplo:

• Permite generar un archivo XML de documentación del código que hemos programado. Otro día si me acuerdo explicaré como.
• Nos permite conocer qué hacen las clases y métodos, qué parámetros reciben, que valores devuelven,etc.

Estos comentarios se añaden poniendo ///, tras lo cual el propio Visual añade la estructura del comentario. A continuación un ejemplo y su utilidad:

///<summary>

/// Descripcion breve de que hace el metodo PermitirAcceso

///</summary>

///<remarks>

/// Descripcion detallada (este es opcional)

///</remarks>

///<param name="Edad">Edad de la persona que quiere acceder</param>

///<returns>Devuelve true si la persona es mayor de 18 </returns>

public bool PermitirAcceso(int Edad)

{

     if (Edad => 18)

     {

          return true;

     }

     else

     {

          return false;

     }

}

Si ahora queremos llamar a esta función desde cualquier otro sitio, al empezar a introducir su nombre nos aparece la descripción breve del método:

Y si seguimos escribiendo, al abrir el paréntesis nos muestra una ayuda con los parámetros que tenemos que pasar y su descripción.

Podemos definir los parámetros que queramos e incluso sobrecargas si ponemos las etiquetas correspondientes antes de cada método. En el caso de sobrecargas, los campos de summary y returns han de coincidir en todos los métodos.