Por que você nunca deve ignorar comentários ao escrever código

Por mais que o nosso projeto possua uma documentação, é bem comum sentirmos a necessidade de documentar alguns trechos do código, explicando o que está acontecendo ali ou explicar o que uma determinada função faz, o que ela espera e o que ela devolve. Tudo bem que com Typescript isso não é tão "problemático" assim, IDEs como o Visual Studio Code utilizam a tipagem que fazemos no código como informação quando utilizamos/chamamos uma função/método/objeto "tipado". Isso ajuda bastante, porém, isso não é possível no Javascript, e mesmo no Typescript, você pode sentir a necessidade de explicar mais sobre aquela função, dar um exemplo ou mesmo explicar mais sobre os argumentos e o retorno. Sendo assim, vamos ver um pouco sobre comentários em Javascript (e claro, você pode usar para outras linguagens, modificando pouca ou nenhuma coisa da syntax).

Índice 📖

• Introdução
• Tipos de comentário
• Comentário em linha
• Comentário em bloco
• Comentário de bloco descritivo
• Um pouco mais
• Considerações finais

Introdução ✍

Comentar o código é um divisor de águas, alguns desenvolvedores vêm como algo ruim: "se precisa ser explicado, o código não está tão bom assim", "variáveis e funções descritivas são melhores do que blocos de código". Por outro lado, tem quem defenda os comentários, com argumentos como: "Você não precisa analisar toda uma função para saber o que ela faz", "existem trechos complexos que mesmo um código descritivo não resolve".
Eu acredito que existem situações e situações, como tudo na tecnologia/vida, um framework/linguagem pode ser a melhor escolha para um problema X, assim como comentar ou não o código pode ser a melhor escolha pro projeto Y e a roupa Z a melhor escolha para certas ocasiões.
Sendo assim, me deparei com um projeto onde apesar de trabalhar sozinho(inicialmente), ficará um bom tempo rodando na empresa, e por isso decidi comentar, tanto para dar a prévia dos argumentos de funções (Vscode IntelliSense), quanto descreva-las o mais simples possível, pensando justamente em futuros devs que vão manter o projeto.
Sendo assim, vou mostrar aqui algumas boas práticas e dicas, além de mostrar alguns tipos de comentários para cada etapa do seu código.

Tipos de comentário 📚

Temos dois principais tipos ou estilos de comentários, e cada um serve bem para certo momento do código, podemos optar por algo mais simples, em uma única linha ou algo com mais linhas e bem mais informativo, que pode até passar informações como autor, parâmetros, retorno, exemplos etc.

Comentário em linha

Comentários em linha são o tipo mais simples, e presente em quase todas as linguagens de programação, consiste basicamente em iniciarmos um comentário em uma única linha, acima, abaixo ou do lado do código que queremos falar sobre.
No Javascript, utilizados duas barras (//) para tal:

// Procurar numeros maiores do que o passado dentro do array informado
function numeroMaiorQue(array, numero){
  const encontrados = array.find(elemento => elemento > numero);

  return encontrados;
}

Utilizei um comentário em linha para descrever o que a função numerosMaiorQue() faz, dessa forma, eu consigo deixar claro o que está acontecendo ali. Tudo bem, até aqui, nada de surpreendente.

Comentários em bloco

Outra opção para comentários são os comentários em blocos, que consistem em um comentário que inicia e fecha em um intervalo de linhas, caso você queira escrever bastante informação:

/*
* Função que recebe um array e compara
* item a item do array para encontrar
* os maiores do que item passado 
* argumento da função.
*/
function numeroMaiorQue(array, numero){
  const encontrados = array.find(elemento => elemento > numero);

  return encontrados;
}

Abrimos o comentário com /* na primeira linha e fechamos algumas linhas depois com */, podendo escrever livremente nesse intervalo, tendo quebra de linhas etc(usei * em todas as linhas apenas para deixar mais organizado, não é obrigatório).
E se quisermos melhorar ainda mais esse comentário, é possível? SIM!

Comentários de bloco descritivo

É aqui onde a coisa brilha! Uma das opções que mais gosto de usar e que fica muito bom para outros devs, principalmente quando estamos trabalhando com Javascript, são os comentários de bloco descritivo, onde podemos passar algumas propriedades no comentário o qual a nossa IDE vai interpretar e apresentar quando formos usá-lo, por exemplo:

/**
* @description Filtrar array de numeros maiores do que o valor passado.
*
* @param {Array} array
* @param {Number} numero
* @param {Number} numeros
**/
function numeroMaiorQue(array, numero){
  const encontrados = array.find(elemento => elemento > numero);

  return encontrados;
}

Desta forma, deixamos bem claro qual a descrição da nossa função, ou seja, o que ela faz, quais argumentos ela recebe e o tipo deles e o retorno dessa função também com o tipo. Se você usar uma IDE ou editor de código que dê suporte a esse tipo de comentário (Visual Studio Code por exemplo), vai ter um resultado similar a esse quando fazer a chamada dessa função:

Podemos também, além do nome do argumento, escrever uma descrição para ela, basta dar um espaço depois do nome e escrever:

/**
* @description Filtrar array de numeros maiores do que o valor passado.
*
* @param {Array} array array com os numeros para procurar.
* @param {Number} numero numero a ser procurado.
* @param {Number} numeros numeros que serão retornados.
**/
function numeroMaiorQue(array, numero){
  const encontrados = array.find(elemento => elemento > numero);

  return encontrados;
}

Podemos ver que ao chamar a função, o editor já nos traz as informações que colocamos no nosso comentário, como a descrição, o retorno e podemos ver os tipos dos argumentos também.
Podemos perceber que o parâmetro "array" está como um array de any, que seria algo como "array de qualquer coisa", assim como o retorno, e o número é do tipo number, então ainda podemos melhorar um pouco mais a tipagem do array para deixar ainda mais informativo.
Vamos melhorar isso usando o conceito de Generics que também é usado no Typescript, ficando dessa forma:

Basicamente, o que fizemos aqui foi adicionar o tipo dos itens do array, dizendo que é um array de números (Array<Number>), dessa forma, não teremos mais a IDE exibindo any[], e conseguimos deixar tudo mais claro:

Um pouco mais 🔥

Até aqui nossos comentários já estão bem legais e explicativos, mas vamos supor que tenhamos outra função, que recebe um objeto, e queremos "tipar" esse objeto e suas propriedades, como podemos fazer isso? Simples:

/**
* @description Recebe um usuario e salva no banco de dados
*
* @param {object} usuario objeto de usuário 
* @param {string} usuario.nome nome do usuario
* @param {string} usuario.sobrenome sobrenome do usuario
* @param {Number} usuario.idade idade do usuario
* @param {string} usuario.sexo sexo do usuario
**/
function salvarUsuario({nome, sobrenome, idade, sexo}){
  try {
    BD.gravar('usuario', {nome, sobrenome, idade, sexo });
    return true;
  } catch(_){
    return false;
   }
}

Nesse exemplo temos uma função que recebe um objeto (já estou desestruturando para que fique mais claro, e também ajuda no intellisense da IDE) de usuário com várias propriedades, então no nosso comentário, basta dizer qual o nome do objeto e o tipo, nesse caso é um object e o nome será usuario e em seguida vamos "tipar" as propriedades que estão dentro do objeto usuario, que são: nome, sobrenome, idade e sexo, temos como resultado:

E dá pra fazer isso em classes? SIM!
Vamos imaginar que tenhamos uma classe para gerenciar o usuário e que temos um método nela para gerar um id aleatório para o usuário, então vamos documentar tanto a classe quanto esse método, ficando dessa forma:

/**
 * @description Classe para gerenciar o usuario
* 
* @author Tulio Calil
*
*/
class Usuario {
 /**
  * @description Gerar id aleatorio para o usuario
  * 
  * @return {Number} id do usario
  *
  */
  gerarId(){
   return Math.random() * (10000,1) + 1;
  }
 }

E com isso vamos ter o seguinte resultado:

Considerações finais ✅

Esse foi meu primeiro post aqui no dev.to, tentei passar da melhor forma possível tudo que aprendi quando precisei me aprofundar mais na documentação do código, espero que tenham gostado!

Vale lembrar também que você pode usar a lib JSDoc para gerar arquivos html da sua documentação a partir desses mesmos comentários (eu acho isso fantástico).

Como eu disse no começo, essas dicas também servem para várias outras linguagens como Java e Php, também existem libs que gera documentação para elas (Javadoc e phpDocumentor).

Você pode consultar aqui todas as tags que você pode usar nos comentários de bloco.

Muito obrigado a Victoria Trindade pela revisão do texto e correções ❤

Até a próxima!