Comentarios de código

Cuando escribas código, te acostumbrarás rápidamente al hecho de que casi todas las palabras y caracteres que escribes tienen un significado especial. Por ejemplo, en C# te encontrarás un gran número de palabras clave como class, namespace, public y muchas más. Verás que el compilador se asegura de que estés usando de manera correcta esas palabras clave, así como tu propias variables y métodos. C# es un lenguaje bastante estricto y el compilador te ayudará a asegurarte de que todo el código está escrito correctamente. De todas formas, tienes la posibilidad de escribir cualquier texto de cualquier manera, mediante el uso de los comentarios de código

Probablemente ya has experimentado los comentarios en algún código que hayas visto, sea C# o cualquier otro lenguaje de programación - el concepto de comentarios en código es universal. La forma en que son escritos varía bastante, así que vamos a ver algunos de los tipos de comentarios que puedes usar en tu código de C#.

Comentarios de una línea

El tipo de comentario más básico en C# es el comentario de una línea. Como su nombre indica, convierte una línea en un comentario - veamos cómo se vería:

// My comments about the class name could go here...
class Program
{
    ......

Eso es todo: Inicia tus líneas con dos diagonales (//) y tu texto pasará de algo que el compilador revisa y se queja de ello, a algo que el compilador ignora completamente. Y ya que esto sólo aplica a la línea con las diagonales, eres libre de hacer lo mismo en la línea siguiente, esencialmente usando comentarios de una línea para crear comentarios de múltiples líneas:

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
    ...... 

Comentarios con múltiples líneas

En caso de querer escribir comentarios de múltiples lineas, tiene más sentido usar la alternativa para comentarios de multiples lineas que ofrece C#. En lugar de incluir el prefijo en cada linea, puedes ingresar un carácter con secuencia al comienzo y al final (start y stop). Todo entre estos será tratado como comentarios.

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
    ...and use indentation, if you want to!  
*/  
class Program  
{
    ......

Use la secuencia de inicio de diagonal-asterisco (/*), escriba lo que quieras, en varias líneas o no, y luego finaliza todo con la secuencia de finalización de asterisco-diagonal (*/). Entre esos marcadores, puedes escribir lo que quieras.

Al igual que con casi cualquier otro tema relacionado con la programación, a menudo se debate si se deben usar múltiples comentarios de una sola línea o un comentario de varias líneas. Personalmente, uso ambos para diferentes situaciones: al final, ¡todo depende de usted!

Comentarios de documentación

Los comentarios de documentación (a veces referidos como comentarios de documentación XML) lucen como comentarios comunes, pero con XML integrado. Como los comentarios regulares, estos vienen en dos formas: En línea única y múltiples líneas. Tú también puedes escribirlos de la misma manera, pero con un carácter extra. Entonces, los comentarios de Documentación XML de línea única usan tres diagonales (///) en vez de dos, en la variante de líneas múltiples lleva un asterisco extra agregado en el delimitador de inicio. Veamos como luce:

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

Aquí se pueden ver ambas variantes: comentarios de una línea y comentarios multi-línea. El resultado es el mismo, pero el primer caso es el mas utilizado para comentarios de documentación.

Documentar tus tipos y sus miembros con comentarios de documentación es un tema muy grande, y por eso será cubierto más a fondo en un artículo posterior, pero ahora ¡ya sabes cómo lucen!

Comentarios de codigo & la lista Tareas

Si estás usando Visual Studio, puedes conseguir cierta ayuda localizando tus comentarios en el código. En la ventana Task List (accede a esta desde el menú View > Task List), Tus comentarios aparecerán si usan la especial, pero sencilla sintaxis para comentar de las Task List.

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

Así que si el comentario de una línea es inmediatamente seguido por la palabra 'TODO' o 'HACK', va a aparecer en la Lista de Tareas de Visual Studio, así:

Y hay más tipos - dependiendo en la versión de Visual Studio que estés usando, va a responder a unos o todos de los siguientes símbolos de comentarios:

• TODO
• HACK
• NOTE
• UNDONE

Tú puedes incluso agregar tus propias marcas, si así lo quieres - solo sigue los pasos descritos en este artículo.

Resumen

Los comentarios en el código son extremadamente útiles para documentar el código y dejar pistas para ti mismo o un potencial colega sobre como funciona todo. Como un beneficio adicional, son especialmente útiles cuando se quiere probar algo: sólo hay que tomar una linea, comentarla y agregar lo que se quiere probar para ver como funciona el código. Si el resultado no es exitoso, se descomenta la línea original y se vuelve a donde se estaba.

Y no te preocupes de que el usuario final pueda leer tus comentarios pues estos son, como se ha mencionado antes, completamente ignorados por el compilador y por lo no tanto no están incluídos de ninguna manera en el archivo EXE o DLL final. Los comentarios en el código son tu espacio personal cuando escribes código así que escribe tus comentarios de la forma que mas te convenga.