Comentários: anotações para você e para outros programadores

Aprenda a usar comentários para explicar seu código e torná-lo mais compreensível.

Imagine que você está escrevendo um livro de receitas. Você não colocaria apenas os ingredientes e o modo de preparo, certo? Provavelmente adicionaria dicas, explicações sobre por que um ingrediente é importante, ou sugestões de acompanhamento.

No mundo da programação, os comentários são exatamente isso: anotações que você adiciona ao seu código para explicar o que ele faz, por que ele faz de um certo jeito, ou para deixar lembretes para você mesmo ou para outros programadores que possam ler seu código no futuro.

Por que usar comentários?

  1. Clareza: O código, por si só, nem sempre é óbvio. Comentários ajudam a explicar a lógica complexa, a intenção por trás de uma decisão de design, ou o propósito de uma função específica.
  2. Manutenção: Meses depois de escrever um código, você pode não se lembrar de todos os detalhes. Comentários servem como um "mapa" para você mesmo.
  3. Colaboração: Se você trabalha em equipe, comentários são essenciais para que outros desenvolvedores entendam rapidamente o seu código sem precisar te perguntar a cada linha.
  4. Depuração (temporário): Você pode usar comentários para "desativar" temporariamente partes do código que estão causando problemas, sem precisar apagá-las.

Como fazer comentários em JavaScript?

Existem duas formas principais de adicionar comentários em JavaScript:

1. Comentários de uma única linha (//)

Este tipo de comentário é usado para anotações curtas que cabem em uma única linha. Tudo o que vier depois de // até o final da linha será ignorado pelo JavaScript.

Exemplo:

// Este é um comentário de uma única linha.
// O JavaScript vai ignorar tudo que estiver aqui.

console.log("Olá, Mundo!"); // Este comentário explica o que a linha faz

Você pode colocar o comentário em uma linha separada ou no final de uma linha de código.

2. Comentários de múltiplas linhas (/* ... */)

Este tipo de comentário é usado para anotações mais longas que precisam de várias linhas. Tudo o que estiver entre /* e */ será ignorado pelo JavaScript.

Exemplo:

/*
Este é um comentário de múltiplas linhas.
Ele pode se estender por quantas linhas forem necessárias.
É útil para explicar blocos de código maiores,
ou para documentar funções e arquivos.
*/

let nome = "Maria"; // Declara uma variável para guardar o nome
let idade = 30;     // Declara uma variável para guardar a idade

/*
  A função abaixo exibe uma mensagem de boas-vindas
  personalizada para o usuário, usando o nome e a idade.
  Ela foi criada para ser reutilizável em diferentes partes do sistema.
*/
function saudarUsuario(nomeUsuario, idadeUsuario) {
    console.log(`Olá, ${nomeUsuario}! Você tem ${idadeUsuario} anos.`);
}

saudarUsuario(nome, idade);

Boas práticas para comentários:

  • Comente o "porquê", não o "o quê": Evite comentar o óbvio. // Soma dois números acima de let resultado = a + b; é redundante. Em vez disso, explique por que você está somando esses números ou por que essa soma é importante naquele contexto.
  • Mantenha-os atualizados: Um comentário desatualizado é pior do que nenhum comentário, pois pode enganar quem lê o código. Se você mudar o código, lembre-se de atualizar os comentários.
  • Não exagere: Código limpo e bem escrito, com nomes de variáveis e funções claros, já é uma forma de documentação. Comentários devem complementar, não substituir, um bom código.
  • Use para desativar código temporariamente: Se você está testando algo ou precisa desabilitar uma parte do código por um tempo, comentar é uma ótima opção.
// console.log("Esta linha está desativada temporariamente para teste.");

Comentários são uma ferramenta poderosa para tornar seu código mais compreensível e fácil de trabalhar, tanto para você no futuro quanto para qualquer pessoa que venha a colaborar no seu projeto. Use-os com sabedoria!