Comentários em JavaScript

Introdução

Este capítulo aborda tudo o que você precisa saber para escrever bons comentários em JavaScript: as duas sintaxes de comentário (// para comentários de linha e /* */ para comentários de bloco), doc-comentários JSDoc para documentar funções, a diferença entre comentários úteis e prejudiciais, e como comentar código durante a depuração. Comentários são textos que o motor JavaScript ignora completamente durante a execução — eles existem puramente para humanos. Eles explicam o seu código para qualquer pessoa que o leia posteriormente, incluindo o seu eu do futuro e seus colegas de equipe. Por serem removidos da execução, comentários não têm custo em tempo de execução. (Uma diretiva relacionada que é lida pelo motor é "use strict"; apesar de parecer uma string no topo de um arquivo, ela muda como o código é executado — veja o capítulo sobre modo estrito.)

Por que Comentar é Essencial em JavaScript

Comentar pode parecer secundário, mas desempenha um papel fundamental na programação. Ele ajuda em:

• Documentação de código: Para explicar lógicas complexas ou o raciocínio por trás de determinados trechos de código.
• Legibilidade do código: Melhorando a compreensão do fluxo e da funcionalidade do código.
• Depuração: Habilitando ou desabilitando facilmente partes do código durante testes ou depuração.
• Colaboração em equipe: Ajudando outros desenvolvedores a entender o seu processo de pensamento.

Tipos de Comentários em JavaScript

JavaScript suporta dois tipos principais de comentários:

Comentários de Linha Única

Comentários de linha única começam com // e se estendem até o fim da linha atual. Tudo após // naquela linha é ignorado. Eles podem ficar em sua própria linha ou ao final de uma linha de código (um comentário inline):

// This whole line is a comment
let a = 5, b = 10;

let sum = a + b; // inline comment: add the two values

Como um comentário // só vai até o final da linha, a linha seguinte volta ao código normal — você não precisa "fechá-lo".

Comentários Multilinha

Comentários multilinha (também chamados de comentários de bloco) começam com /* e terminam com */. Tudo entre eles é ignorado, mesmo ao longo de várias linhas. Use-os para explicações mais longas:

/*
  Returns the sum of two numbers.
  Both arguments are expected to be numbers;
  passing strings will concatenate instead of add.
*/
function add(a, b) {
    return a + b;
}

Você também pode usar a sintaxe de bloco no meio de uma linha, por exemplo para rotular um argumento: setTimeout(run, 1000 /* ms */).

Atenção — comentários de bloco não podem ser aninhados. Um */ encerra o comentário na primeira ocorrência, portanto envolver código que já contém /* ... */ em outro comentário de bloco causa problemas. O */ interno fecha o comentário prematuramente e o restante passa a ser código ativo:

/*
  /* inner */
  alert('this still runs!');
*/

Copiar

Para comentar uma região que contém comentários de bloco, use // em cada linha.

Bons vs. Maus Comentários: Explique o Porquê, Não o Quê

A regra mais útil: comente o porquê, não o quê. O código já diz o que faz; um bom comentário captura a intenção, a troca ou a restrição surpreendente que o código não consegue expressar por si só.

// Bad: just restates the code — adds noise, can go stale
let total = 0; // set total to 0

// Good: explains a non-obvious constraint
const RETRY_LIMIT = 3; // the payment API rejects bursts above 3 calls/sec

Prefira código autodocumentado a comentários sempre que possível. Uma variável bem nomeada ou uma pequena função frequentemente elimina a necessidade de um comentário:

// Needs a comment because the intent is hidden:
if (u.a && Date.now() - u.l < 86400000) { /* active in last 24h */ }

// No comment needed — the names say it:
const isActive = user.isVerified && wasSeenInLast24Hours(user);
if (isActive) {
  // ...
}

Algumas diretrizes adicionais:

1. Mantenha-os atualizados. Um comentário que contradiz o código é pior do que nenhum comentário — os leitores não sabem em qual confiar.
2. Seja conciso. Explique o raciocínio, não cada etapa.
3. Não deixe código morto comentado permanentemente. Delete-o; o controle de versão o guarda.

Comentando Código

Durante a depuração, muitas vezes você quer desabilitar uma linha ou bloco sem excluí-lo. Prefixe uma linha com //, ou envolva uma região em /* */:

let value = compute();
// console.log('Debug:', value); // temporarily silenced

/*
expensiveLogging(value);
sendToAnalytics(value);
*/

Isso é ótimo para isolar qual parte do código está causando um problema. Muitos editores alternam isso com um atalho de teclado. Veja o capítulo sobre Console API para alternativas mais limpas ao uso excessivo de console.log para depuração.

Marcadores TODO e FIXME

Uma convenção comum é marcar trabalhos inacabados com TODO (algo a fazer depois) ou FIXME (um bug conhecido). Editores e linters podem listar esses marcadores para você:

// TODO: optimize this loop for large data sets
// FIXME: breaks when input is an empty array

JSDoc: Documentando Funções

JSDoc é um padrão para documentar funções usando um comentário de bloco especial que começa com /** (dois asteriscos). Tags como @param e @returns descrevem as entradas e a saída. Ferramentas e editores leem esses comentários para exibir dicas inline e gerar documentação HTML.

/**
 * Adds two numbers together.
 * @param {number} a - The first addend.
 * @param {number} b - The second addend.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
    return a + b;
}

console.log(add(2, 3)); // 5

JSDoc funciona especialmente bem com funções: documentar parâmetros e tipos de retorno torna o contrato de uma função claro sem precisar ler seu corpo. Outras tags comuns incluem @throws, @example e @deprecated.

Conclusão

Incorporar comentários eficazes em JavaScript não é apenas uma prática de programação, mas uma habilidade de comunicação. Isso contribui significativamente para a manutenibilidade e escalabilidade do código. Ao dominar os comentários em JavaScript, você não apenas melhora o seu código, mas também aprimora a colaboração com outras pessoas no processo de desenvolvimento.

Lembre-se: um código bem comentado é reflexo de um desenvolvedor cuidadoso e profissional. Abrace o poder dos comentários e veja o seu código JavaScript se transformar em um recurso mais acessível e fácil de manter.

Prática