Comentários em programação são usados para fornecer contexto adicional para o código ou deixar anotações para você e outras pessoas. Comentários são linhas ou blocos de texto que são ignorados pelo mecanismo JavaScript quando seu código é executado. Eles estão lá exclusivamente para o benefício das pessoas que estão lendo o código, seja você ou outra pessoa. JavaScript oferece duas maneiras de adicionar comentários ao seu código: comentários de uma linha e comentários de múltiplas linhas. Comentários de linha única são criados usando duas barras (//). Aqui está um exemplo:

// I am a single line comment in JavaScript

Este tipo de comentário é ótimo para explicações ou esclarecimentos breves. Aqui está um exemplo do mundo real dos arquivos do projeto do currículo G.E.A.R ACADEMY:

// This is to allow English to build without having to download the i18n files.
// It fails when trying to resolve the i18n-curriculum path if they don't exist.
const curriculumLocale = process.env.CURRICULUM_LOCALE ?? 'english';
const I18N_CURRICULUM_DIR = path.resolve(
  __dirname,
  curriculumLocale === 'english' ? '.' : 'i18n-curriculum/curriculum'
);

Não se preocupe em tentar entender o que o código está realmente fazendo porque ele é mais avançado do que o que você aprendeu até agora. Instead, focus on the comment left by the developer. Este comentário fornece um contexto importante para explicar por que este código existe. Comentários como este são importantes para quem trabalha em equipes por dois motivos: 1. Outros desenvolvedores trabalhando no projeto entenderão o propósito deste código. 1. Ele ajuda a prevenir alterações ou exclusões desnecessárias sem consultar a equipe, o que poderia levar a bugs ou problemas. Outro tipo de comentário são os comentários de múltiplas linhas. Aqui está a sintaxe básica:

/*
 I am a multiline comment.
 This is helpful for longer explanations.
*/

Comentários multilinha são úteis quando você precisa escrever descrições, explicações ou notas mais longas no seu código. Vamos dar mais uma olhada nos arquivos do projeto do currículo do G.E.A.R ACADEMY para ver como comentários multilinha podem ser usados no mundo real.

/* Since there can be more than one way to complete a certification (using the
legacy curriculum or the new one, for instance), we need a certification
field to track which certification this belongs to. */
const dupeCertifications = [
  {
    certification: 'responsive-web-design',
    dupe: '2022/responsive-web-design'
  }
];
const hasDupe = dupeCertifications.find(
  cert => cert.dupe === meta.superBlock
);

Assim como antes, ignore todo o código JavaScript porque ele usa conceitos que ainda não foram ensinados. Em vez disso, concentre-se no comentário deixado pelo desenvolvedor. Um desenvolvedor da equipe, ou até mesmo um novo colaborador trabalhando no projeto, pode entender por que este trecho de código está aqui e ter o contexto completo antes de trabalhar nesta área do projeto. Embora os comentários sejam úteis na programação, é importante evitar o excesso de comentários. Você não precisa comentar cada linha de código, especialmente se o código for direto e autoexplicativo. Aqui está um exemplo de uso de comentários para explicar o óbvio:

// This code uses the const keyword to create a new variable called price.
// We are assigning the number 10 to the price variable.
const price = 10;

Nesta situação, não há necessidade de adicionar comentários aqui porque o código é autoexplicativo. O objetivo é melhorar a legibilidade, não sobrecarregar o código com explicações desnecessárias. Se você quiser adicionar comentários aos seus projetos pessoais enquanto está aprendendo a programar, tudo bem. Mas uma vez que você comece a trabalhar em projetos do mundo real com outros desenvolvedores, é importante não usar comentários para código que seja autoexplicativo. Também é importante não usar comentários para ajudar a explicar código confuso, excessivamente complicado ou mal escrito. Nessas situações, o melhor é refatorar ou alterar seu código para que outros desenvolvedores entendam melhor o que está acontecendo. Comentários são ferramentas poderosas para documentar seu código e torná-lo mais fácil de entender. Você deve usar comentários para fornecer contexto ou deixar notas para você e outras pessoas.