Comentários em C: // e /* */ explicados

Um comentário é um texto que o compilador joga fora. Ele existe só para as pessoas que vão ler o código depois, e uma delas normalmente é você. C oferece duas formas, e entender quando cada uma é a ferramenta certa leva uns dois minutos.

As duas formas

#include <stdio.h>

int main(void) {
    // Um comentário de uma linha: tudo depois de // até o fim da linha.

    /* Um comentário de bloco.
       Ele pode ocupar quantas linhas você quiser
       e só termina no marcador de fechamento. */

    printf("Comentários nunca chegam à saída.\n");  // eles também podem vir depois do código
    return 0;
}

Execute: a saída é uma linha só. Os dois comentários foram apagados antes de o compilador sequer analisar o programa - eles não custam nada em tempo de execução e não acrescentam nada ao executável.

// vai até o fim da linha física. Nada pode vir depois dele naquela linha, então isto não funciona do jeito que parece:

int x = 5;  // define x como cinco  int y = 6;   /* y nunca é declarado */

/* ... */ termina no primeiro */, onde quer que ele esteja. Pode começar e terminar no meio de uma linha, o que é útil de vez em quando:

int total = preco /* antes do imposto */ + frete;

Por que existem dois estilos

/* */ é o C original, de 1972. // veio do C++ e só foi oficialmente adicionado ao C no C99. Essa história explica algo que você vai notar ao ler código mais antigo: bibliotecas escritas para serem portáveis para C89 usam /* */ até para comentários de uma linha, porque // não compilaria nas ferramentas antigas que elas ainda suportavam.

Hoje todo compilador que você provavelmente vai usar aceita os dois. Use // para observações comuns e /* */ quando um comentário realmente ocupar várias linhas. Se você estiver mirando um compilador embarcado muito antigo, confira antes de depender de //.

Comentários não podem ser aninhados

Esta é a única armadilha de verdade:

/* Desativar esta seção por enquanto
   int a = compute();
   /* o auxiliar clássico - fique de olho nele */
   int b = a * 2;
*/

O comentário de bloco termina no primeiro */, que é o da linha 3. As linhas 4 e 5 voltam a ser código ativo, e o */ final da linha 6 é um erro de sintaxe. A mensagem do compilador aponta para a última linha e é completamente inútil quanto à causa.

A solução é usar o pré-processador, que lida com aninhamento:

#if 0
    int a = compute();
    /* o auxiliar clássico - fique de olho nele */
    int b = a * 2;
#endif

#if 0 nunca é verdadeiro, então o pré-processador apaga tudo até o #endif antes de o compilador ver. Isso sobrevive a comentários, aspas e outros blocos #if lá dentro, e é fácil de procurar quando você for fazer a limpeza.

Comentar código durante a depuração

Remover uma linha temporariamente é o uso mais comum de comentários no dia a dia. Quando um programa se comporta mal, desativar uma instrução por vez te diz qual delas importa.

#include <stdio.h>

int main(void) {
    int total = 0;

    for (int i = 1; i <= 5; i++) {
        total += i;
        // printf("passo %d: total = %d\n", i, total);  /* ative para rastrear */
    }

    printf("Total final: %d\n", total);
    return 0;
}

Descomente o printf e execute de novo para ver o laço montando a resposta. Rastrear com prints não é elegante, mas em C é rápido e sempre funciona - um depurador te diz mais, e um printf te diz algo imediatamente.

Dois hábitos evitam que isso vire bagunça. Apague o código comentado antes de fazer o commit; o controle de versão lembra da versão antiga para você. E quando você deixar uma linha desativada de propósito, diga por quê em uma nota ao lado.

Comentários de documentação

Um comentário de bloco acima de uma função é onde você explica o que ela faz, o que seus parâmetros significam e o que há de surpreendente nela.

#include <stdio.h>

/*
 * celsius_to_fahrenheit
 * ---------------------
 * Converte uma temperatura em graus Celsius para graus Fahrenheit.
 *
 *   c: a temperatura de entrada, em Celsius
 *
 * Retorna a temperatura equivalente em Fahrenheit.
 */
double celsius_to_fahrenheit(double c) {
    return c * 9.0 / 5.0 + 32.0;
}

int main(void) {
    printf("100C = %.1fF\n", celsius_to_fahrenheit(100.0));
    printf("0C   = %.1fF\n", celsius_to_fahrenheit(0.0));
    return 0;
}

Ferramentas como o Doxygen leem comentários estruturados assim e geram documentação de referência. O estilo do próprio Doxygen usa /** ... */ com as marcações @param e @return:

/**
 * Converte Celsius para Fahrenheit.
 * @param c temperatura em Celsius
 * @return a mesma temperatura em Fahrenheit
 */
double celsius_to_fahrenheit(double c);

Qualquer um dos dois serve para o seu próprio código. O que importa é que o comentário fique ao lado da declaração que as pessoas leem - no arquivo de cabeçalho, tipicamente - em vez de enterrado na implementação.

O que vale a pena comentar

A regra que sobrevive ao contato com bases de código reais: comente o porquê, não o quê.

i++;  // incrementa i          <- não diz nada que o código já não dissesse

/* Pula o BOM: arquivos exportados pelo sistema antigo começam com
   três bytes que não fazem parte dos dados. */
offset += 3;

O segundo comentário contém informação que não está em lugar nenhum do código. O primeiro é ruído que uma hora vai contradizer a linha que descreve, porque comentários não são atualizados quando o código muda.

Coisas que realmente merecem um comentário especificamente em C:

• De quem é esta memória. Se uma função retorna um ponteiro que quem chamou precisa liberar com free, diga isso. C não tem como expressar isso no tipo.
• Unidades e faixas. int timeout; é ambíguo - segundos ou milissegundos?
• Correção não óbvia. Por que o laço para em n - 1, por que este cast é seguro, por que o buffer tem 256 bytes.
• Estranheza deliberada. Código que parece um bug mas não é atrai "correções" de futuros leitores, a menos que esteja sinalizado.

#include <stdio.h>
#include <string.h>

int main(void) {
    char name[32];  /* 31 caracteres mais o '\0' terminador */

    /* strncpy NÃO acrescenta um terminador se a origem encher o buffer,
       então escrevemos um nós mesmos. */
    strncpy(name, "Ada Lovelace", sizeof(name) - 1);
    name[sizeof(name) - 1] = '\0';

    printf("Nome: %s\n", name);
    return 0;
}

Esse comentário merece o lugar dele: a linha abaixo parece redundante e não é.

Comentários dentro de strings não são comentários

Um último detalhe. Marcadores de comentário não têm significado especial dentro de um literal de string ou de uma constante de caractere:

#include <stdio.h>

int main(void) {
    printf("Progresso: 50%% // não é um comentário\n");
    printf("O caminho é /* ainda só texto */\n");
    return 0;
}

As duas linhas são impressas por inteiro. O compilador tokeniza as strings antes de procurar comentários, então // dentro de aspas é simplesmente dois caracteres. (O %% da primeira linha é como se imprime um sinal de porcentagem literal com printf - % sozinho inicia um especificador de formato.)