Você já abriu um código antigo e sentiu que estava lendo hieróglifos? Ou pior, teve medo de apagar uma linha “estranha” e quebrar todo o sistema? O código que funciona é importante, mas o código que pode ser lido e mantido é o que define um desenvolvedor profissional.

Capa: JavaScript Comentários - Essencial para o humano, ignorado pela máquina

Neste guia, vamos aprender como os comentários em JavaScript funcionam e como usá-los para fornecer contexto sem transformar seu arquivo em um diário poluído.

Como os Comentários Funcionam “Debaixo do Capô”

O primeiro conceito que você deve entender é que os comentários servem exclusivamente para humanos. Quando o motor do JavaScript (JS Engine) lê o seu código, ele identifica os blocos de comentário e os descarta antes da execução.

Mecanismo de Execução: Comentários são ignorados pelo Runtime e não afetam a performance

Isso significa que você pode (e deve) adicionar contexto sem se preocupar com a velocidade do site. Eles não afetam a performance.

A Sintaxe dos Comentários em JavaScript

Existem duas formas principais de deixar notas no seu código, dependendo da extensão da explicação necessária.

1. Comentários de Linha Única

Ideais para notas rápidas ou esclarecimentos breves. Você os ativa usando as duas barras inclinadas (//). Tudo o que estiver após as barras naquela linha será ignorado.

Sintaxe: Linha Única usando Double Slash

Exemplo de Uso Prático: Eles são perfeitos para explicar uma lógica específica de fallback ou prevenir erros de build em partes isoladas do script.

Caso de Uso: Contexto para prevenir erros de build

2. Comentários de Bloco (Multi-linha)

Quando a explicação é mais complexa, como a documentação de uma função ou uma regra de arquitetura, usamos o bloco que abre com /* e fecha com */.

Sintaxe: Bloco Multi-linha com abertura e fechamento

Dica de Profissional: Use esse formato para explicar a regra de negócio por trás de uma estrutura de dados, ajudando colaboradores a entenderem “por que” aquele dado existe.

Caso de Uso: Documentação explicando a regra de negócio por trás dos dados

Por Que Comentar? (O Valor do Sistema)

Comentar não é apenas escrever lembretes. É uma ferramenta de colaboração e segurança.

Tabela de Utilidade: Colaboração, Prevenção e Clareza

  • Colaboração: Dá contexto para outros desenvolvedores (e para o seu “eu” do futuro).
  • Prevenção: Evita que código “estranho”, mas necessário, seja apagado por engano.
  • Clareza: Foca no propósito daquela função, facilitando a manutenção.

O Lado Sombrio: O Anti-Pattern da Redundância

Muitos iniciantes cometem o erro de comentar o que o código faz, em vez de por que ele faz. Explicar a sintaxe óbvia cria ruído visual e dificulta a leitura.

Anti-Pattern: Redundância e Ruído Visual explicando o óbvio

Se o seu código já é autoexplicativo (como declarar uma variável price), você não precisa de um comentário dizendo que está declarando um preço. Remova o excesso!

Refatorar ou Comentar?

Antes de escrever um comentário para explicar um código confuso, pergunte-se: “Eu posso reescrever este código para que ele fique claro sozinho?”.

Fluxograma: Refatoração vs Comentários

A regra de ouro do Clean Code é: Não use comentários para explicar código mal escrito. Refatore-o. Comente apenas se a lógica for intrínseca ao negócio e não puder ser simplificada apenas com nomes de variáveis melhores.

A Regra de Ouro

O segredo de um código profissional é ser explícito. Se o seu código é claro, ele não precisa de muletas.

Regra de Ouro: Não explique o O QUE, explique o PORQUÊ

Use os comentários para documentar a lógica de negócio e as decisões arquiteturais. Deixe que o código fale por si só na sintaxe.

Gostou dessa abordagem? Comece hoje mesmo a limpar seus arquivos e deixe apenas os comentários que realmente agregam valor à sua equipe!