Lição 1: Comunicação na Cabine

Narrativa

Bem-vindo, Piloto! Você acabou de entrar na Academia Æther. Antes de tocar em qualquer controle, precisamos estabelecer uma comunicação clara. Na cabine de um mecha, cada anotação no painel serve como referência vital durante missões críticas. Assim como pilotos experientes deixam registros no log de voo para si mesmos e para a equipe de manutenção, você aprenderá a documentar seu código.

Aqui na Academia, chamamos comentários de Anotações de Voo. Elas não afetam o funcionamento do mecha, mas são essenciais para manter a ordem mental quando o caos da batalha se instala. Um Piloto que não documenta é um Piloto que esquece. Vamos aprender a arte de comunicar intenções através do código.

Conceito

Em Rust, comentários são trechos de texto que o Engenheiro de Montagem (compilador) ignora completamente. Eles existem apenas para humanos lerem e entenderem o código. Existem três tipos principais de comentários:

Comentários de Linha Única (//): Tudo após // até o final da linha é ignorado. Use para notas rápidas e explicações pontuais:

let velocidade = 100; // Velocidade máxima em km/h

Comentários de Múltiplas Linhas (/* */): Permitem comentar blocos maiores de texto. Útil para desativar temporariamente código durante manutenção:

/*
    Este bloco contém
    múltiplas linhas de
    explicação detalhada
*/

Comentários de Documentação (/// e //!): Especiais do Rust que geram documentação automática. /// documenta o item seguinte (função, struct), enquanto //! documenta o módulo/crate atual:

/// Calcula a energia restante do núcleo
/// 
/// # Exemplos
/// let energia = calcular_energia(100, 20);

Comentários efetivos explicam o porquê, não o o quê. Código bom se explica; comentários explicam decisões.

Requisitos

• Entrada: Código-fonte Rust contendo diferentes tipos de comentários
• Processamento: Analisar, contar, adicionar e remover comentários do código
• Saída: Código processado com métricas de documentação e legibilidade melhorada

Design de Dados

Esta lição trabalha com manipulação de texto puro. Não definimos structs ou enums complexos — focamos em operações sobre strings que representam código-fonte:

// Funções de processamento de código
pub fn contar_linhas(codigo: &str) -> usize;
pub fn remover_comentarios(linha: &str) -> String;
pub fn adicionar_comentario(linha: &str, comentario: &str) -> String;
pub fn eh_comentario(linha: &str) -> bool;

As funções operam em string slices (&str) para eficiência de memória, retornando String quando novos valores precisam ser alocados.

Diagrama Conceitual

flowchart TD
    A[Código-Fonte] --> B{Análise}
    B -->|Contar| C[Total de Linhas]
    B -->|Remover| D[Código Limpo]
    B -->|Adicionar| E[Código Documentado]
    B -->|Verificar| F[Identifica Comentários]
    C --> G[Legibilidade]
    D --> G
    E --> G
    F --> G

Funções e Módulos

//! Lição 1: Comunicação na Cabine
//!
//! Primeiro passo no treinamento de um piloto da Academia Æther.

/// Conta o número de linhas de um código-fonte (incluindo comentários)
pub fn contar_linhas(codigo: &str) -> usize;

/// Remove todos os comentários de uma linha de código
pub fn remover_comentarios(linha: &str) -> String;

/// Adiciona um comentário explicativo a uma linha de código
pub fn adicionar_comentario(linha: &str, comentario: &str) -> String;

/// Verifica se uma linha contém apenas um comentário de linha única
pub fn eh_comentario(linha: &str) -> bool;

Exemplo do Conceito

// Comentário INEFICAZ - apenas repete o código
let x = 5; // Atribui 5 a x

// Comentário EFETIVO - explica a intenção
let x = 5; // Valor inicial do contador de tentativas

/*
    Documentação de módulo usando /* */
    Explica o propósito geral desta seção
*/

/// Função bem documentada com doc comment
/// 
/// # Parâmetros
/// * `nome` - Identificação do piloto
/// 
/// # Retorna
/// Mensagem de boas-vindas formatada
pub fn saudar(nome: &str) -> String {
    format!("Bem-vindo, Piloto {}!", nome)
}

fn main() {
    // Código auto-explicativo - sem comentário necessário
    let nome = "Silva";
    let mensagem = saudar(nome);
    println!("{}", mensagem);
}

Explicação:

• Linha 1-2: Exemplo de comentário ruim que apenas descreve o óbvio
• Linha 4-5: Comentário útil explicando o significado do valor
• Linha 7-10: Bloco de comentário para documentação extensa
• Linha 12-17: Doc comment (///) que gera documentação automática
• Linha 21: Código claro não precisa de comentário

Missão

1. Implementar contar_linhas: Conte quantas linhas existem em um código-fonte, considerando que linhas vazias também contam
2. Implementar remover_comentarios: Remova o comentário de linha (//) de uma string, retornando apenas o código
3. Implementar adicionar_comentario: Adicione um comentário explicativo ao final de uma linha de código
4. Implementar eh_comentario: Verifique se uma linha inteira é apenas um comentário (começa com // opcionalmente precedido por espaços)

Diagrama de Fluxo da Missão

flowchart TD
    A[Tarefa: Comentar Código] --> B[Implementar contar_linhas]
    B --> C[Implementar remover_comentarios]
    C --> D[Implementar adicionar_comentario]
    D --> E[Implementar eh_comentario]
    E --> F[Testes verificam]
    F --> G{Clippy limpo?}
    G -->|Sim| H[Concluído]
    G -->|Não| I[Corrigir warnings] --> F

Como Executar

# Executar testes
cargo test

# Verificar lint
cargo clippy -- -D warnings

# Formatar código
cargo fmt --check

Dicas

• Use split('\n') ou lines() para separar linhas de código
• Para encontrar //, procure pela primeira ocorrência e ignore se estiver dentro de strings
• trim_start() ajuda a verificar se uma linha começa com comentário ignorando espaços
• Doc comments (///) também começam com // — considere isso na implementação
• Teste seus casos limite: linha vazia, linha só com espaços, comentário no meio do código