Os dois tipos de comentários em JavaScript
O JavaScript tem duas sintaxes de comentário. O comentário de linha única começa com // e vai até o fim da linha:
Um comentário de bloco começa com /* e termina no próximo */. Ele pode ocupar quantas linhas você quiser:
As duas formas são totalmente ignoradas pelo motor do JavaScript. Elas existem para os humanos — para você, para quem trabalha com você e para o seu "eu do futuro" que vai reler esse código daqui a seis meses.
Comentário de linha única
O // é o que você vai usar na maior parte do tempo. Tudo que vier depois do // na mesma linha é comentário; a linha seguinte volta a ser código normal:
Comentários no final da linha (depois de uma instrução) funcionam bem para anotações curtas. Se a observação for longa a ponto de quebrar linha, mova ela para uma linha própria acima do código — comentários finais muito longos acabam truncados pelos editores e ignorados por quem lê.
Comentário de bloco em JavaScript
Vale a pena usar /* */ em duas situações: quando o comentário precisa de mais de uma linha e quando ele aparece no meio de uma expressão.
Uma pegadinha: comentários de bloco não aninham. O primeiro */ encerra o comentário, mesmo que você achasse que ainda estava dentro de um bloco externo:
/* externo /* interno */ ainda externo */
// SyntaxError — o primeiro */ fechou o bloco,
// e "ainda externo */" agora é código inválido.
Quando precisar comentar um trecho de código que já contém /* */, use // em cada linha.
Comentando código temporariamente
Na hora de depurar, é bem comum querer desativar algumas linhas só por um momento. As duas formas de comentário funcionam:
Todo editor tem um atalho pra isso — Ctrl+/ no Windows/Linux e Cmd+/ no Mac — que adiciona ou remove // nas linhas selecionadas. Decore esse atalho: você vai usar todo santo dia.
Código comentado deve ser algo temporário. Não suba pro repositório cemitérios de código morto com // versão antiga, deixei aqui por garantia em cima. O controle de versão já guarda o histórico pra você. Pode deletar sem medo.
Comente o porquê, não o quê
Essa é a regra de ouro que separa comentário útil de barulho. O código já mostra o que está sendo feito. Um bom comentário explica o porquê.
Barulho:
Esses comentários não dizem absolutamente nada que o próprio código já não mostre. Compare:
Os dois comentários apontam algo que o leitor jamais deduziria só olhando o código — uma restrição externa, uma peculiaridade documentada. Esse é o padrão. Se remover o comentário não deixar ninguém perdido, ele não estava cumprindo seu papel.
JSDoc: comentários que as ferramentas entendem
JSDoc é uma convenção para escrever comentários de bloco que descrevem funções de forma estruturada. Editores e verificadores de tipo leem esses comentários e, com base neles, oferecem autocomplete mais preciso e documentação no hover:
A abertura com /** (duas estrelas) é o que diferencia o JSDoc de um comentário de bloco comum. Você não precisa colocar JSDoc em toda função — ele vale mais a pena em APIs públicas, utilitários compartilhados e em qualquer lugar onde os tipos não fiquem óbvios só pelo código.
Alguns hábitos que vale a pena cultivar
- Mantenha o comentário colado no código que ele descreve. Um comentário dez linhas acima da parte relevante costuma perder o sincronismo conforme o código muda.
- Atualize o comentário quando alterar o código. Um comentário desatualizado é pior do que nenhum — ele mente ativamente para quem vai ler depois.
- Prefira nomes melhores a mais comentários.
const d = 86400000;pede um comentário.const MILLISECONDS_PER_DAY = 86_400_000;não precisa. - Sinalize pendências com
TODO:ouFIXME:. A maioria dos editores destaca essas marcações, e dá para encontrá-las facilmente com um grep depois.
HTML vs JavaScript: cuidado para não misturar os comentários
Se você está escrevendo JavaScript dentro de um arquivo HTML, preste atenção para não confundir os dois estilos de comentário. O HTML usa <!-- -->, já o JavaScript usa // e /* */. Dentro de uma tag <script>, só funcionam as formas do JavaScript:
<script>
// Correto — comentário JS dentro de <script>
/* Também correto */
<!-- Errado — isto é um comentário HTML e vai quebrar seu JS -->
console.log("oi");
</script>
Os navegadores historicamente toleravam <!-- --> dentro de scripts por causa de compatibilidade com navegadores bem antigos, mas pode considerar isso como obsoleto e seguir em frente.
Próximo passo: declarando variáveis
Agora que você já sabe comentar o código, é hora de escrever algum. O JavaScript tem três formas de declarar uma variável — let, const e var — e escolher a certa é a primeira decisão de verdade que você vai tomar a cada linha. É o que veremos a seguir.
Perguntas frequentes
Como escrever um comentário em JavaScript?
Use // para comentar uma linha — tudo que vier depois dele naquela linha é ignorado pelo interpretador. Para várias linhas, use /* ... */. Os dois funcionam em qualquer lugar de um arquivo .js e também dentro de tags <script> no HTML.
Qual a diferença entre // e /* */ em JavaScript?
O // vale até o fim da linha atual e para por aí. Já o /* */ começa no /* e só termina no próximo */, então ele pode cobrir várias linhas ou aparecer no meio de uma expressão. Na prática: use // para anotações curtas e /* */ quando precisar de mais de uma linha ou quiser comentar parte de uma expressão.
Como comentar um bloco de código em JavaScript?
Envolva o trecho com /* */ ou coloque // no começo de cada linha. A maioria dos editores tem atalho pronto para isso — Ctrl+/ (ou Cmd+/ no Mac) alterna o // nas linhas selecionadas. Só evite aninhar /* */ dentro de outro /* */: o primeiro */ fecha o comentário externo e você vai tomar um erro de sintaxe.
Quando vale a pena escrever um comentário?
Comente o porquê, não o o quê. Se o código está fazendo algo fora do óbvio — uma gambiarra, uma regra de negócio, um truque de performance — explique o motivo. Não fique narrando o que o código já diz sozinho. Um nome de variável ou função bem escolhido elimina boa parte da necessidade de comentário.
