Comentarios en C: // y /* */ explicados

Un comentario es texto que el compilador descarta. Existe puramente para las personas que leerán el código después, una de las cuales normalmente eres tú. C ofrece dos formas, y saber cuándo cada una es la herramienta correcta toma unos dos minutos.

Las dos formas

#include <stdio.h>

int main(void) {
    // Un comentario de una linea: todo lo que sigue a // hasta el final de la linea.

    /* Un comentario de bloque.
       Puede abarcar tantas lineas como quieras
       y solo termina en el marcador de cierre. */

    printf("Los comentarios nunca llegan a la salida.\n");  // tambien pueden ir al final del codigo
    return 0;
}

Ejecútalo: la salida es una sola línea. Ambos comentarios se eliminaron antes de que el compilador siquiera analizara el programa; no cuestan nada en tiempo de ejecución y no añaden nada al ejecutable.

// llega hasta el final de la línea física. Nada puede ir después en esa línea, así que esto no funciona como parece:

int x = 5;  // asigna cinco a x  int y = 6;   /* y nunca se declara */

/* ... */ termina en el primer */, esté donde esté. Puede empezar y terminar a mitad de línea, lo cual resulta útil de vez en cuando:

int total = price /* antes de impuestos */ + shipping;

Por qué existen dos estilos

/* */ es el C original, de 1972. // vino de C++ y solo se añadió oficialmente a C en C99. Esa historia explica algo que notarás al leer código antiguo: las bibliotecas escritas para ser portables a C89 usan /* */ incluso para comentarios de una línea, porque // no habría compilado en las cadenas de herramientas viejas que aún daban soporte.

Hoy todo compilador que es probable que uses acepta ambos. Usa // para comentarios ordinarios y /* */ cuando un comentario realmente abarque varias líneas. Si tu objetivo es un compilador embebido muy antiguo, verifica antes de confiar en //.

Los comentarios no se pueden anidar

Esta es la única trampa real:

/* Desactivar esta seccion por ahora
   int a = compute();
   /* el ayudante clasico: no le quites el ojo */
   int b = a * 2;
*/

El comentario de bloque termina en el primer */, que es el de la línea 3. Las líneas 4 y 5 vuelven entonces a ser código vivo, y el */ final de la línea 6 es un error de sintaxis. El mensaje del compilador apunta a la última línea y no ayuda en nada a entender la causa.

La solución es usar el preprocesador, que sí maneja el anidamiento:

#if 0
    int a = compute();
    /* el ayudante clasico: no le quites el ojo */
    int b = a * 2;
#endif

#if 0 nunca es verdadero, así que el preprocesador elimina todo hasta #endif antes de que el compilador lo vea. Sobrevive a comentarios, comillas y otros bloques #if dentro, y es fácil de buscar cuando haces limpieza.

Comentar código mientras depuras

Quitar temporalmente una línea es el uso cotidiano más común de los comentarios. Cuando un programa se porta mal, desactivar una instrucción a la vez te dice cuál importa.

#include <stdio.h>

int main(void) {
    int total = 0;

    for (int i = 1; i <= 5; i++) {
        total += i;
        // printf("paso %d: total = %d\n", i, total);  /* activalo para rastrear */
    }

    printf("Total final: %d\n", total);
    return 0;
}

Descomenta el printf y ejecuta otra vez para ver cómo el bucle construye su respuesta. Rastrear con impresiones no es elegante, pero en C es rápido y siempre funciona: un depurador te dice más, y un printf te dice algo de inmediato.

Dos hábitos evitan que esto se convierta en un desastre. Borra el código comentado antes de confirmarlo; el control de versiones recuerda la versión anterior para que tú no tengas que hacerlo. Y cuando dejes una línea desactivada a propósito, di por qué en una nota al lado.

Comentarios de documentación

Un comentario de bloque encima de una función es donde explicas qué hace, qué significan sus parámetros y cualquier cosa sorprendente sobre ella.

#include <stdio.h>

/*
 * celsius_to_fahrenheit
 * ---------------------
 * Convierte una temperatura en grados Celsius a grados Fahrenheit.
 *
 *   c: la temperatura de entrada, en Celsius
 *
 * Devuelve la temperatura equivalente en Fahrenheit.
 */
double celsius_to_fahrenheit(double c) {
    return c * 9.0 / 5.0 + 32.0;
}

int main(void) {
    printf("100C = %.1fF\n", celsius_to_fahrenheit(100.0));
    printf("0C   = %.1fF\n", celsius_to_fahrenheit(0.0));
    return 0;
}

Herramientas como Doxygen leen comentarios estructurados como estos y generan documentación de referencia. El estilo propio de Doxygen usa /** ... */ con etiquetas @param y @return:

/**
 * Convierte Celsius a Fahrenheit.
 * @param c temperatura en Celsius
 * @return la misma temperatura en Fahrenheit
 */
double celsius_to_fahrenheit(double c);

Cualquiera de los dos sirve para tu propio código. Lo que importa es que el comentario viva junto a la declaración que la gente lee, normalmente en el archivo de cabecera, en lugar de quedar enterrado en la implementación.

Qué vale la pena comentar

La regla que sobrevive al contacto con bases de código reales: comenta el porqué, no el qué.

i++;  // incrementa i          <- no dice nada que el codigo no dijera

/* Saltar el BOM: los archivos exportados por el sistema antiguo empiezan
   con tres bytes que no forman parte de los datos. */
offset += 3;

El segundo comentario contiene información que no está en ninguna parte del código. El primero es ruido que acabará contradiciendo a la línea que describe, porque los comentarios no se actualizan cuando el código cambia.

Cosas que realmente valen un comentario en C específicamente:

• Quién es dueño de esta memoria. Si una función devuelve un puntero que quien la llama debe liberar con free, dilo. C no tiene forma de expresar eso en el tipo.
• Unidades y rangos. int timeout; es ambiguo: ¿segundos o milisegundos?
• Corrección no evidente. Por qué el bucle se detiene en n - 1, por qué esta conversión es segura, por qué el búfer es de 256 bytes.
• Rarezas deliberadas. El código que parece un error pero no lo es atrae "arreglos" de futuros lectores a menos que esté etiquetado.

#include <stdio.h>
#include <string.h>

int main(void) {
    char name[32];  /* 31 caracteres mas el '\0' terminador */

    /* strncpy NO agrega un terminador si el origen llena el bufer,
       asi que lo escribimos nosotros mismos. */
    strncpy(name, "Ada Lovelace", sizeof(name) - 1);
    name[sizeof(name) - 1] = '\0';

    printf("Nombre: %s\n", name);
    return 0;
}

Ese comentario se gana su lugar: la línea de abajo parece redundante y no lo es.

Los comentarios dentro de cadenas no son comentarios

Un último detalle. Los marcadores de comentario no tienen significado especial dentro de un literal de cadena ni de una constante de carácter:

#include <stdio.h>

int main(void) {
    printf("Progreso: 50%% // no es un comentario\n");
    printf("La ruta es /* solo texto */\n");
    return 0;
}

Ambas líneas se imprimen completas. El compilador tokeniza las cadenas antes de buscar comentarios, así que // entre comillas son simplemente dos caracteres. (El %% de la primera línea es cómo se imprime un signo de porcentaje literal con printf: un % solo inicia un especificador de formato).