Comentarios en Rust

Los comentarios son notas que dejas en tu código para que las lean otras personas (o tú mismo en el futuro). Rust los ignora por completo al compilar, así que nunca cambian cómo funciona tu programa. Un buen comentario explica por qué el código hace algo, no solo qué hace.

Comentarios de línea

El comentario más común empieza con //. Todo lo que va después de // en esa línea se ignora:

fn main() {
    // Esto es un comentario: Rust lo salta por completo
    println!("¡Hola!"); // los comentarios también pueden ir al final de una línea
}

Salida:

¡Hola!

▶ Pruébalo tú mismo

Comentarios de varias líneas

Para una nota más larga, puedes empezar cada línea con //:

fn main() {
    // Este programa saluda al usuario.
    // Muestra una sola línea de texto.
    // Escrito como primer ejemplo.
    println!("¡Hola!");
}

Salida:

¡Hola!

▶ Pruébalo tú mismo

Rust también admite comentarios de bloque entre /* y */, que pueden ocupar varias líneas:

fn main() {
    /*
      Esto es un comentario de bloque.
      Puede ocupar varias líneas
      sin poner // en cada una.
    */
    println!("¡Hola!");
}

Salida:

¡Hola!

▶ Pruébalo tú mismo

En la práctica, la mayor parte del código de Rust usa // incluso para varias líneas. Es lo habitual en la comunidad y funciona muy bien con los atajos del editor.

Comentar código

Los comentarios son muy útiles para desactivar una línea por un rato mientras pruebas algo:

fn main() {
    println!("Esto se ejecuta");
    // println!("Esto está desactivado por ahora");
}

Salida:

Esto se ejecuta

▶ Pruébalo tú mismo

Escribir comentarios que ayuden

Un comentario que repite el código no aporta nada. El código ya dice qué pasa. Un buen comentario dice por qué, o avisa de algo que quien lee no puede ver:

fn main() {
    let minutes = 135;

    // El temporizador solo muestra horas completas. La división entera
    // descarta el resto, que es justo lo que queremos aquí.
    let hours = minutes / 60;
    let leftover = minutes - hours * 60; // minutos que no llegaron a una hora completa

    println!("{hours} h {leftover} min");
}

Salida:

2 h 15 min

▶ Pruébalo tú mismo

Compáralo con un comentario como // divide los minutos entre 60. Es cierto, pero cualquiera puede leer minutes / 60. La información útil es por qué dividir es correcto aquí.

Algunos hábitos más que vale la pena adquirir:

Mantén los comentarios al día. Un comentario que ya no coincide con el código es peor que no tener ninguno, porque la gente confía en él.
// TODO: es una forma habitual de marcar trabajo pendiente, como // TODO: manejar números negativos. Muchos editores lo resaltan y pueden listar todos los TODO de un proyecto.
Los comentarios de bloque se pueden anidar en Rust. A diferencia de C, puedes envolver en otro comentario un código que ya contiene un comentario /* */, y sigue funcionando:

fn main() {
    /* Desactivado por ahora:
       println!("saludo viejo"); /* saludaba a todo el mundo */
    */
    println!("saludo nuevo");
}

Salida:

saludo nuevo

▶ Pruébalo tú mismo

Comentarios de documentación

Rust tiene un tipo especial de comentario que empieza con /// (tres barras). Son los comentarios de documentación (doc comments): describen funciones, y Rust puede convertirlos en un sitio web de documentación navegable con cargo doc.

/// Suma dos números y devuelve el resultado.
fn add(a: i32, b: i32) -> i32 {
    a + b
}

Como principiante todavía no necesitas comentarios de documentación. Solo recuerda que /// es para documentar y // es para notas normales. Cuando estés listo, la página de Documentación te muestra cómo escribirlos, generar la documentación e incluso convertir los ejemplos en tests.

Práctica

1. Desactiva una línea

Este programa imprime tres líneas. Convierte la línea del medio en un comentario para que solo se impriman Línea 1 y Línea 3. Pista: pon // al principio de la línea que quieres desactivar.

fn main() {
    println!("Línea 1");
    println!("Línea 2");
    println!("Línea 3");
}

Ver solución

fn main() {
    println!("Línea 1");
    // println!("Línea 2");
    println!("Línea 3");
}

Salida:

Línea 1
Línea 3

▶ Pruébalo tú mismo

2. Desactiva dos líneas a la vez

Ahora imprime de Línea 1 a Línea 4, pero usa un solo comentario de bloque para desactivar las líneas 2 y 3. Pista: empieza el comentario con /* antes de la línea 2 y termínalo con */ después de la línea 3.

Ver solución

fn main() {
    println!("Línea 1");
    /*
    println!("Línea 2");
    println!("Línea 3");
    */
    println!("Línea 4");
}

Salida:

Línea 1
Línea 4

▶ Pruébalo tú mismo

Resumen

Los comentarios son notas que Rust ignora; úsalos para explicar tu código.
// inicia un comentario de línea (el tipo más común).
/* ... */ es un comentario de bloque para varias líneas, y los comentarios de bloque se pueden anidar.
Los buenos comentarios explican por qué, no lo que el código ya dice.
/// es un comentario de documentación que sirve para generar documentación.

Comprueba lo que aprendiste

Comprueba lo aprendido

1. ¿Qué hace Rust con los comentarios cuando compila tu código?

2. ¿Para qué sirven los comentarios de documentación ///?

Puntuación: 0 / 2

Para leer más

Comments: The Rust Book (en inglés): la breve sección oficial sobre los comentarios // y dónde se suelen poner.
Comments: Rust by Example (en inglés): todos los estilos de comentario en un solo ejemplo ejecutable, incluidos comentarios de bloque dentro de una expresión.
Making Useful Documentation Comments: The Rust Book (en inglés): un primer vistazo a /// y //!, y a cómo los usa cargo doc.
How to write documentation: The rustdoc book (en inglés): consejos sobre qué debe contener un buen comentario de documentación, para cuando escribas una biblioteca.
Comments: The Rust Reference (en inglés): las reglas exactas, incluidos los comentarios de bloque anidados.