Comentários em Rust

Quem começa a programar em Rust logo percebe que a linguagem incentiva clareza, não só na sintaxe, mas também na forma como documentamos o que o código faz. E, para isso, nada melhor do que comentários. Eles não são lidos pelo compilador, mas fazem toda a diferença para quem lê o código depois (inclusive você mesmo no futuro).

Assim como outros recursos da linguagem, os comentários em Rust seguem padrões bem definidos. Vamos dar uma olhada no que existe e em como usá-los bem.

Comentários de linha

O formato mais comum começa com duas barras (//). Tudo depois delas, até o fim da linha, é ignorado pelo compilador.

// Exibe uma mensagem de boas-vindas
println!("Olá, mundo!");

Quando o comentário precisa de várias linhas, basta repetir // em cada uma:

// Aqui estamos preparando uma operação importante.
// Ela exige alguns passos intermediários, então deixamos
// este bloco explicado para facilitar a manutenção.

Esse estilo é simples, rápido e muito usado.

Comentários ao lado do código

Às vezes você quer comentar uma linha específica, sem interromper o fluxo visual.

fn main() {
    let porta = 8080; // porta padrão do servidor
}

Mas o padrão mais comum em Rust segue outra linha: deixar o comentário logo acima da instrução que ele explica.

fn main() {
    // porta padrão do servidor
    let porta = 8080;
}

Comentários de documentação

Além dos comentários comuns, Rust tem um segundo tipo muito importante: os comentários de documentação, usados para gerar documentação automática. Eles são escritos com ///

/// Retorna o dobro de um número.
///
/// # Exemplo
///
/// ```rust
/// let resultado = dobrar(4);
/// assert_eq!(resultado, 8);
/// ```
fn dobrar(x: i32) -> i32 {
    x * 2
}