comentarios

¿Qué son los comentarios?

Los comentarios son textos explicativos insertados en el código fuente para facilitar su comprensión por parte de los programadores. No forman parte del código ejecutable y el compilador los ignora por completo durante el proceso de compilación.

También sirven para detectar errores durante la depuración. Si no logras localizar el origen de un fallo, puedes comentar fragmentos de código sospechosos: al ser ignorados por el compilador, podrás aislar el problema paso a paso.

Los comentarios son como las anotaciones que escribíamos en los libros de texto en el colegio; aportan información extra que simplifica el entendimiento del contenido principal.

Tipos de comentarios

Tipo de comentario	Marcador de apertura	Marcador de cierre	Reglas fundamentales
Comentario de una sola línea Single-line	//	Final de la línea actual	Afecta únicamente a la línea completa; todo el texto tras // en esa línea se descarta
Comentario de bloque Delimited	/*	*/	Cubre varias líneas o fragmentos dentro de una línea; no admite anidamiento
Comentario de documentación Documentation	///	Final de la línea actual	Incorpora etiquetas XML, destinado a generar automáticamente la documentación API del proyecto

1. Comentarios de una sola línea //

1. Todo lo que va desde // hasta el final de la línea actual es ignorado por el compilador;
2. Se pueden colocar al principio de la línea o después del código funcional;
3. No tienen restricciones de anidamiento y no generan conflictos sintácticos con los comentarios de bloque /* */.

// Comentario al inicio de línea: declarar variable numérica
int num = 10; // Comentario tras el código: almacena el valor 10
// int temp = 99; // Toda la línea comentada para depuración; desactiva código temporalmente sin borrarlo, fácil de restaurar despuésLenguaje del código: JavaScript (javascript)

2. Comentarios de bloque /* */

1. Requieren marcadores de apertura y cierre emparejados; todo el contenido entre /* y */ se ignora;
2. Permiten cubrir varias líneas completas y también fragmentos parciales dentro de una línea;
3. Está prohibido anidar comentarios de bloque. El compilador finaliza el comentario en el primer */ que encuentre, y cualquier */ suelto restante provocará errores de sintaxis.

Ejemplo básico

/*
Ejemplo de comentario de bloque multilínea
El compilador omite todo el contenido interior
Se puede escribir texto en cualquier cantidad de líneas
*/
string str = "Prueba";Lenguaje del código: JavaScript (javascript)

/*
Multi-line delimited comment example
All content here is ignored by the compiler
Text can span any number of lines
wellcome to foxdevelop.com
*/
string greet = "wellcome to foxdevelop.com";
Console.WriteLine(greet);Lenguaje del código: JavaScript (javascript)

El anidamiento genera errores de compilación

Si incluyes otro bloque de comentarios dentro de uno exterior, el último marcador de cierre no tendrá una apertura correspondiente y fallará la compilación.

Comentarios parciales en línea

Solo ocultan un fragmento de código; en el ejemplo siguiente la variable a queda completamente comentada.

int /*a,*/ b; 
// Equivale a int b; el trozo "a," entre los marcadores queda excluido de la ejecuciónLenguaje del código: JavaScript (javascript)

Ejemplo incorrecto de anidamiento de bloques

Provoca error de sintaxis

/* Apertura del comentario exterior
    /* Comentario interno anidado (solo se lee como texto normal, sin efecto) */
// El primer */ anterior cierra el bloque exterior, el último */ no tiene apertura asociada y genera fallo sintáctico
*/Lenguaje del código: JavaScript (javascript)

El símbolo /* dentro de // no activa un comentario de bloque

Los marcadores de bloque se interpretan como texto corriente dentro del comentario de una línea y no funcionan como tal.

// Esto es un comentario simple /* el símbolo /* aquí es solo texto, no abre un bloque
int x = 5;
/* Se abre el bloque de comentario */ // El bloque finaliza aquí, el // posterior funciona con normalidadLenguaje del código: JavaScript (javascript)

3. Comentarios de documentación ///

1. Tienen una apariencia similar a los comentarios simples, se marcan con tres barras inclinadas consecutivas ///;
2. Admiten etiquetas XML integradas; los IDE y herramientas los leen para generar documentación de referencia API;
3. Se colocan habitualmente encima de clases, métodos y propiedades para documentar interfaces públicas.

/// <summary>
/// Clase principal, punto de entrada de la aplicación
/// </summary>
class Program
{
    /// <summary>
    /// Método de entrada del programa
    /// </summary>
    /// <param name="args">Vector con los argumentos de línea de comandos</param>
    static void Main(string[] args)
    {

    }
}Lenguaje del código: JavaScript (javascript)

Resumen

1. Los comentarios de bloque /* */ no admiten anidamiento; la lectura del comentario finaliza inmediatamente al encontrar el primer */;
2. Los comentarios simples // solo afectan a su propia línea, no se extienden a otras líneas; cualquier /* contenido se trata como carácter literal;
3. La sintaxis y comportamiento de comentarios simples y de bloque en C# son idénticos a C/C++;
4. Buenas prácticas al escribir comentarios: no repitas el significado literal del código, prioriza explicar el propósito de negocio y la lógica de diseño para simplificar el mantenimiento futuro. Los comentarios que solo copian nombres de variables no aportan ningún valor.
5. Explicaciones cortas en línea, desactivación temporal de una línea de código → usa //
6. Desactivación masiva de varias líneas, ocultación parcial de fragmentos dentro de una línea → usa /* */
7. Documentar interfaces de clases/métodos, generar documentación automática del proyecto → usa ///

* Cómo generar la documentación

El siguiente apartado es solo de referencia. Los comentarios de documentación se emplean fundamentalmente en proyectos grandes; en la fase de aprendizaje basta con conocer su existencia.

Pasos en Visual Studio

1. Haz clic derecho en el proyecto → Propiedades → pestaña Compilar (Build);
2. Marca la casilla: Generate XML documentation file (Generar archivo de documentación XML);
3. Ruta de salida por defecto: bin\Debug\NombreProyecto.xml, se puede personalizar la ruta de guardado;
4. Aplica la configuración a All Configurations (Todas las configuraciones) para que funcione en Debug y Release;
5. Recompila el proyecto; aparecerá un archivo XML completo con todos los comentarios en el directorio destino.

Configuración por consola .NET CLI (sin Visual Studio)

Abre el archivo .csproj del proyecto y añade este nodo:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>Lenguaje del código: HTML, XML (xml)

Ejecuta el comando de compilación:

dotnet build

Funcionamiento

Este archivo XML almacena todo el contenido de etiquetas como <summary>、<param>、<returns>, sirviendo como fuente de datos para generar la documentación oficial. Además, Visual Studio lo lee para mostrar los comentarios en los tooltips flotantes de IntelliSense.

Otras herramientas de documentación

DocFX oficial de Microsoft (recomendado por la marca, genera sitios web estáticos HTML de documentación)

Sandcastle (herramienta clásica de Microsoft para crear archivos de ayuda offline en formato CHM)

Herramientas ligeras de terceros (como Doxygen)

Los tres tipos de sintaxis de comentarios ya explicados