Dominando los comentarios en C#: Tipos, mejores prácticas y documentación XML

Comentarios en C#

En este artículo, aprenderemos sobre los comentarios en C#, los diferentes estilos y por qué y cómo usarlos eficazmente en un programa.

Los comentarios son la savia del código legible. Son anotaciones legibles por humanos que explican la intención, aclaran lógica compleja y documentan decisiones de diseño. El compilador los ignora por completo, por lo que no afectan el rendimiento en tiempo de ejecución.

Según la documentación oficial de Microsoft, C# soporta tres estilos principales de comentarios:

1. Comentarios de una línea (//)
2. Comentarios de varias líneas (/* */)
3. Comentarios de documentación XML (///)

---

Comentarios de una línea

Los comentarios de una línea comienzan con doble barra // y se extienden hasta el final de la línea. Todo lo que sigue a // es ignorado por el compilador.

int a = 5 + 7; // Sumando 5 y 7

Aquí, Sumando 5 y 7 es el comentario.

Ejemplo 1: Usando un comentario de una línea

// Programa Hola Mundo
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) // La ejecución comienza en Main
        {
            // Imprime Hola Mundo
            Console.WriteLine("Hello World!");
        }
    }
}

El programa anterior contiene tres comentarios de una línea:

// Programa Hola Mundo
// La ejecución comienza en Main
// Imprime Hola Mundo

Aunque puedes colocar un comentario en la misma línea que el código, la mejor práctica es mantener los comentarios en líneas separadas para evitar desorden.

---

Comentarios de varias líneas

Los comentarios de varias líneas comienzan con /* y terminan con */. Pueden abarcar varias líneas, lo que los hace ideales para explicaciones en bloque o deshabilitar temporalmente bloques de código.

Ejemplo 2: Usando un comentario de varias líneas

/* Este es un programa Hola Mundo en C#.
   Este programa imprime Hola Mundo. */
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) {
            /* Imprime Hola Mundo */
            Console.WriteLine("Hello World!");
        }
    }
}

El programa incluye dos comentarios de varias líneas:

/* Este es un programa Hola Mundo en C#. Este programa imprime Hola Mundo. */
/* Imprime Hola Mundo */

Nota que un solo bloque /* … */ puede reemplazar a un comentario de una línea cuando se desea brevedad.

---

Comentarios de documentación XML

Los comentarios de documentación XML comienzan con tres barras /// y permiten a los desarrolladores incrustar metadatos estructurados directamente en el código. Estos comentarios son extraídos por herramientas como Visual Studio para generar archivos XML de documentación externa, que pueden ser usados por IDEs para proporcionar tooltips de IntelliSense y por generadores de documentación.

Si eres nuevo en XML, consulta ¿Qué es XML?.

Ejemplo 3: Usando un comentario de documentación XML

/// <summary>
/// Este es un programa hola mundo.
/// </summary>
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) {
            Console.WriteLine("Hello World!");
        }
    }
}

El comentario XML en el ejemplo es:

/// <summary>
/// Este es un programa hola mundo.
/// </summary>

El archivo XML generado se parecería a:

<?xml version="1.0"?>
<doc>
<assembly>
<name>HelloWorld</name>
</assembly>
<members>
</members>
</doc>

Para más detalles, visita Comentarios de documentación XML.

---

Usando comentarios correctamente

Los comentarios eficaces aclaran la intención sin saturar el código. Sobre-comentar puede ocultar la lógica, mientras que sub-comentar dificulta el mantenimiento.

Considera este ejemplo:

// Imprime Hola Mundo
Console.WriteLine("Hello World");

Añadir un comentario aquí es redundante; el código se explica solo. En su lugar, usa comentarios para:

• Explicar algoritmos o lógica de negocio no obvios.
• Resaltar suposiciones, casos边缘 o posibles trampas.
• Describir brevemente el propósito de un bloque, enfocándose en el "por qué" más que en el "cómo".

Recuerda: los comentarios concisos y con propósito son sello de bases de código profesionales.