viernes, 4 de abril de 2014

Etiquetado como:

La importancia de los comentarios en el código fuente

C# y Programación

Artículo para: Programadores de C#

Comentarios

Los comentarios son vitales en nuestro trabajo diario, sobre todo porque como ya habréis observado crear código que uno mismo entiende es sencillo; leer el código de otro programador y entenderlo suele ser  un infierno. Además, el valor añadido de los comentarios XML de los que Visual Studio nos provee: se muestran en el IntelliSense y ayudan a otros programadores a entender qué hacen ciertos métodos, para qué sirven ciertas propiedades, etc…

Por favor, tenedlo muy presente antes de poneros a meter código a lo loco. En ocasiones hacemos cosas tan confusas (bien sea por falta de análisis, o porque no queda más remedio) que es totalmente necesario el comentarlo para que otro, o incluso tú mismo dentro de algún tiempo, lo pueda llegar a entender.

Para ello disponemos de los comentarios de una sola línea…   
public void CorkBreadMethod(bool entry)
{
     if (entry)
     {
          //Code if entry is true
     }
}

…útiles para dar una descripción rápida de lo que estamos haciendo.
También tenemos comentarios de múltiples líneas…
public void CorkBreadMethod(bool entry)
{
     if (entry)
     {
     /* Code if entry is true and loren ipsum when the sun goes
     * down and the moon is dark */

     }
}
… que son de gran utilidad cuando la línea es muy larga y es completamente necesario todo el texto que hemos introducido. Es muy importante tener esto en cuenta, que el texto sea realmente necesario; si no lo es estaremos empantanando el código para el próximo lector. Ver sección al respecto de longitud de línea.

Comentarios XML

Mención especial merecen los comentarios XML ya que son ellos los que permitirán al usuario comprender mejor nuestras clases y métodos. Para utilizarlos, Visual Studio nos provee de una automatización: antes de la clase, propiedad o método (en la línea previa) escribiremos tres veces la barra /// y automáticamente se crearán los encabezados necesarios para el comentario XML:
/// <summary>
/// Class in charge of beign an example
/// </summary>

class CorkBreadClass
{

}


El anterior es un ejemplo de cómo identificar a una clase por medio de un comentario XML. Después de hacerlo, desde fuera de la clase ésta se vería como sigue:


/// <summary>
/// Method inside CorkBreadClass
/// </summary>
/// <param name="entry">A boolean that represents the entry</param>
/// <returns>5 if entry is true, 0 elsewhere...</returns>

public int CorkBreadMethod(bool entry)
{
     return entry ? 5 : 0;
}

Con los anteriores comentarios XML, tendríamos el siguiente resultado:



Como podemos ver en la anterior captura, nos devuelve toda la información que previamente hemos escrito en los comentarios XML, con lo que conseguimos que una persona que no conozca nuestro código o no tenga acceso directo al fuente del mismo; pueda entender qué sucede dentro de nuestras clases.

Enrique Díaz

Author y editor

0 comentarios:

Publicar un comentario

 

Webs amigas:

  • En tu email...

    Suscríbete aquí a nuestro newsletter y nunca más te perderás nuestras actualizaciones

    Copyright © Los vericuetos .NET 2015
    Distributed By My Blogger Themes | Designed By Templateism