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.