Aula 07 – Comentários no Código

O que são Comentários?

Comentários são trechos de texto inseridos no código-fonte que o compilador ignora completamente — eles existem apenas para os seres humanos que leem o código. Um bom comentário explica o porquê de uma decisão de programação, não simplesmente o que a linha faz (o código já mostra isso).

Comentário de Linha: //

O comentário de linha começa com // e se estende até o final da linha. Tudo após o // naquela linha é ignorado pelo compilador. É o tipo mais comum para anotações rápidas e explicações curtas.

#include <stdio.h>

int main() {
    int idade = 25;          // idade do usuário em anos
    float altura = 1.75;     // altura em metros
    float imc;

    // Cálculo do IMC: peso / (altura ao quadrado)
    imc = 70.0 / (altura * altura);

    printf("IMC: %.2f\n", imc); // exibe com 2 casas decimais

    return 0; // encerra o programa com sucesso
}

Comentário de Bloco: /* ... */

O comentário de bloco começa com /* e termina com */. Pode se estender por quantas linhas forem necessárias. É o único tipo de comentário disponível no C original (antes de C99) e é amplamente usado para cabeçalhos de arquivo e documentação de funções.

/*
 * Programa: calculadora_basica.c
 * Autor:    João Silva
 * Data:     2024-03-15
 * Descrição: Demonstra as quatro operações aritméticas
 *            com entrada do usuário.
 */

#include <stdio.h>

/*
 * Função: exibirResultado
 * Parâmetros: op (char) - operador usado
 *             a, b (int) - operandos
 *             resultado (float) - resultado da operação
 */
void exibirResultado(char op, int a, int b, float resultado) {
    printf("%d %c %d = %.2f\n", a, op, b, resultado); /* formatação padronizada */
}

int main() {
    int x = 15, y = 4;

    exibirResultado('+', x, y, x + y);
    exibirResultado('-', x, y, x - y);
    exibirResultado('*', x, y, x * y);
    exibirResultado('/', x, y, (float)x / y); /* cast para divisão real */

    return 0;
}

/* comentário externo /* interno */ ainda comentário? */
// O compilador vê: /* comentário externo /* interno */
// e depois tenta compilar: "ainda comentário? */"  ← ERRO

Desabilitando Código Temporariamente

Uma das utilizações práticas dos comentários é desabilitar temporariamente trechos de código durante o desenvolvimento, sem apagá-los. Isso é útil para testar alternativas ou isolar bugs.

Usando // para comentar linhas individuais

int main() {
    int x = 10;

    // printf("Versão antiga: %d\n", x * 2);  // desabilitada temporariamente
    printf("Versão nova: %d\n", x * x);        // versão atual

    return 0;
}

Usando #if 0 para blocos maiores

Para comentar grandes blocos que já contêm comentários, a técnica mais segura em C é usar a diretiva de pré-processador #if 0:

#include <stdio.h>

int main() {
    int x = 42;

#if 0
    /* Este bloco inteiro é ignorado pelo compilador */
    printf("Código antigo: %d\n", x);
    /* outro comentário interno — sem problema aqui */
    x = x * 2 + 1;
    printf("Resultado antigo: %d\n", x);
#endif

    printf("Resultado atual: %d\n", x); // apenas esta linha executa

    return 0;
}

Boas Práticas de Comentário

Comentar bem é uma habilidade que se desenvolve com a prática. Veja a diferença entre comentários que agregam valor e comentários que apenas repetem o óbvio:

Comentários ruins — evite

// incrementa i em 1
i++;

// declara variável x do tipo int e atribui 5
int x = 5;

// verifica se a é maior que b
if (a > b) {
    // imprime "a é maior"
    printf("a é maior\n");
}

Comentários bons — pratique

// Incrementa i para avançar ao próximo elemento do array
// (arrays em C não têm método .next() como em Java)
i++;

// Usa divisão inteira intencionalmente para descartar os centavos
int valor_em_reais = total_centavos / 100;

// Fórmula de Bhaskara — discriminante negativo indica raízes complexas
float delta = b*b - 4*a*c;
if (delta < 0) {
    printf("Raízes complexas — sem solução real.\n");
    return 1; // encerra com código de erro
}

// Buffer de leitura: +1 para o caractere nulo '\0' que termina strings em C
char nome[51]; // suporta até 50 caracteres + '\0'

Cabeçalho de arquivo — padrão recomendado

Todo arquivo .c ou .h deve começar com um bloco de comentário descrevendo seu propósito:

/*
 * Arquivo:   molecular_energy.c
 * Autor:     Caio Lima Firme
 * Criado em: 2024-01-10
 * Descrição: Cálculo de energia molecular usando o método
 *            Hartree-Fock com base STO-3G.
 *
 * Compilar:  gcc molecular_energy.c -o mol -lm
 */

#include <stdio.h>
#include <math.h>

Documentação Automática com Doxygen

Para projetos maiores, é comum usar comentários no estilo Doxygen — uma ferramenta que lê comentários especialmente formatados e gera documentação HTML ou PDF automaticamente. O estilo usa /** (dois asteriscos) e tags especiais:

/**
 * @brief Calcula a área de um círculo.
 *
 * Utiliza a fórmula: A = π × r²
 * onde π é aproximado por PI_MACRO (3.14159).
 *
 * @param raio  O raio do círculo em metros (deve ser positivo).
 * @return      A área em metros quadrados, ou -1.0 se raio <= 0.
 */
float areaCirculo(float raio) {
    if (raio <= 0) return -1.0f;
    return 3.14159f * raio * raio;
}

Comentários em C versus Java

As sintaxes de comentário são praticamente idênticas nas duas linguagens. A principal diferença está na ferramenta de documentação automática utilizada por cada ecossistema:

Código equivalente nas duas linguagens

/*
 * Calcula o quadrado de um número.
 * @param n - número inteiro
 * @return n ao quadrado
 */
int quadrado(int n) {
    return n * n; // operação simples
}

/**
 * Calcula o quadrado de um número.
 * @param n número inteiro
 * @return n ao quadrado
 */
int quadrado(int n) {
    return n * n; // operação simples
}