Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Comentários e documentação

Os comentários descrevem a intenção do código sem executar o seu conteúdo. Aprende as sintaxes // e /* ... */, a convenção de documentação /** ... */ e como os terminadores de linha podem afetar a análise do programa.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

// comment
/* block comment */
/** documentation comment */

Os comentários explicam o código, sobretudo as razões das decisões e as limitações. O seu conteúdo não é executado como JavaScript. Recomendação editorial: explica principalmente o «porquê», em vez de repetir o que uma instrução óbvia faz.

// inicia um comentário que se prolonga até ao fim da linha ou do texto-fonte; o terminador de linha não faz parte do comentário. /* ... */ pode ocupar parte de uma linha ou várias linhas e termina no primeiro */. Os comentários de bloco não podem ser aninhados.

Para o ECMAScript, /** ... */ é um comentário de bloco normal. A notação de documentação não altera o comportamento de uma função nem impõe tipos; a interpretação de anotações adicionais cabe às ferramentas, não faz parte da sintaxe da linguagem.

Os comentários comportam-se como espaços em branco, com uma exceção importante: durante a análise sintática, um comentário de bloco que contenha um terminador de linha é tratado como um terminador de linha. Isto pode afetar a inserção automática de ponto e vírgula (ASI), por exemplo após return. Não separes return do valor devolvido com um comentário deste tipo. A forma distinta #! só é permitida mesmo no início do texto-fonte de um Script ou Module.

Exemplos

/** Compute the total price. */
function total(price, quantity) {
  // Keep the calculation in one place.
  return price * quantity;
}

const result = total(7, /* quantity */ 3);
console.log(result);

Resultado

21

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes