Comentários em Rust

Comentários são anotações que você deixa no código para outras pessoas lerem. O Rust ignora tudo isso na hora de compilar, então eles nunca mudam o funcionamento do programa. Bons comentários explicam por que o código faz algo, e não só o que ele faz.

Comentários de linha

O comentário mais comum começa com //. Tudo o que vem depois de // naquela linha é ignorado:

fn main() {
    // Isto é um comentário, o Rust ignora esta linha inteira
    println!("Olá!"); // comentários também podem ficar no fim de uma linha
}

Saída:

Olá!

▶ Experimente você mesmo

Comentários de várias linhas

Para uma anotação mais longa, você pode começar cada linha com //:

fn main() {
    // Este programa cumprimenta o usuário.
    // Ele imprime uma única linha de texto.
    // Escrito como primeiro exemplo.
    println!("Olá!");
}

Saída:

Olá!

▶ Experimente você mesmo

O Rust também aceita comentários de bloco entre /* e */, que podem ocupar várias linhas:

fn main() {
    /*
      Isto é um comentário de bloco.
      Ele pode ocupar várias linhas
      sem precisar de // em cada uma.
    */
    println!("Olá!");
}

Saída:

Olá!

▶ Experimente você mesmo

Na prática, a maior parte do código Rust usa // mesmo para várias linhas. É o costume da comunidade e funciona bem com os atalhos dos editores.

Comentando código

Comentários são úteis para desativar uma linha temporariamente enquanto você testa alguma coisa:

fn main() {
    println!("Esta linha roda");
    // println!("Esta está desligada por enquanto");
}

Saída:

Esta linha roda

▶ Experimente você mesmo

Escrevendo comentários que ajudam

Um comentário que repete o código não acrescenta nada. O código já diz o que acontece. Um bom comentário diz por quê, ou avisa sobre algo que quem lê não consegue ver:

fn main() {
    let minutes = 135;

    // O timer só mostra horas inteiras. A divisão de inteiros descarta
    // o resto, que é exatamente o que queremos aqui.
    let hours = minutes / 60;
    let leftover = minutes - hours * 60; // minutos que não completaram uma hora

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

Saída:

2 h 15 min

▶ Experimente você mesmo

Compare isso com um comentário como // divide os minutos por 60. É verdade, mas qualquer pessoa consegue ler minutes / 60. A informação útil é por que dividir é seguro aqui.

Mais alguns hábitos que vale a pena criar:

Mantenha os comentários atualizados. Um comentário que não bate mais com o código é pior do que nenhum comentário, porque as pessoas confiam nele.
// TODO: é um jeito comum de marcar trabalho pendente, como // TODO: tratar números negativos. Muitos editores destacam esse marcador e conseguem listar todos os TODOs de um projeto.
Comentários de bloco podem ser aninhados em Rust. Diferente do C, você pode envolver um código que já tem um comentário /* */ em outro comentário de bloco, e continua funcionando:

fn main() {
    /* Desligado por enquanto:
       println!("saudação antiga"); /* dizia oi para todo mundo */
    */
    println!("nova saudação");
}

Saída:

nova saudação

▶ Experimente você mesmo

Comentários de documentação

O Rust tem um tipo especial de comentário que começa com /// (três barras). São os comentários de documentação (doc comments). Eles descrevem funções, e o Rust consegue transformá-los em um site de documentação navegável com cargo doc.

/// Soma dois números e retorna o resultado.
fn add(a: i32, b: i32) -> i32 {
    a + b
}

Como iniciante, você ainda não precisa de comentários de documentação. Só saiba que /// serve para documentação, e // para anotações comuns. Quando você estiver pronto, a página de Documentação mostra como escrevê-los, gerar a documentação e até transformar exemplos em testes.

Prática

1. Desligue uma linha

Este programa imprime três linhas. Transforme a linha do meio em comentário para que só Linha 1 e Linha 3 sejam impressas. Dica: coloque // no começo da linha que você quer desligar.

fn main() {
    println!("Linha 1");
    println!("Linha 2");
    println!("Linha 3");
}

Ver solução

fn main() {
    println!("Linha 1");
    // println!("Linha 2");
    println!("Linha 3");
}

Saída:

Linha 1
Linha 3

▶ Experimente você mesmo

2. Desligue duas linhas de uma vez

Agora imprima de Linha 1 até Linha 4, mas use um único comentário de bloco para desligar as linhas 2 e 3. Dica: comece o comentário com /* antes da linha 2 e termine com */ depois da linha 3.

Ver solução

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

Saída:

Linha 1
Linha 4

▶ Experimente você mesmo

Resumo

Comentários são anotações que o Rust ignora. Use-os para explicar seu código.
// começa um comentário de linha (o tipo mais comum).
/* ... */ é um comentário de bloco, para várias linhas, e comentários de bloco podem ser aninhados.
Bons comentários explicam por quê, e não o que o código já diz.
/// é um comentário de documentação, usado para gerar documentação.

Teste o que aprendeu

1. O que o Rust faz com os comentários quando compila seu código?

2. Para que servem os comentários de documentação ///?

Pontuação: 0 / 2

Para saber mais

Comments — The Rust Book (em inglês): a seção oficial curtinha sobre comentários // e onde eles costumam ficar.
Comments — Rust by Example (em inglês): todos os estilos de comentário em um exemplo que você pode rodar, incluindo comentários de bloco dentro de uma expressão.
Making Useful Documentation Comments — The Rust Book (em inglês): um primeiro contato com /// e //! e como o cargo doc usa esses comentários.
How to write documentation — The rustdoc book (em inglês): conselhos sobre o que um bom comentário de documentação deve ter, para quando você escrever uma biblioteca.
Comments — The Rust Reference (em inglês): as regras exatas, incluindo comentários de bloco aninhados.