Como sabemos no capítulo Estrutura do código, os comentários podem ser de linha única: começando com // e multilinha: /* ... */ .
Normalmente os usamos para descrever como e por que o código funciona.
À primeira vista, os comentários podem parecer óbvios, mas os novatos em programação costumam usá-los de maneira errada.
Os novatos tendem a usar comentários para explicar “o que está acontecendo no código”. Assim:
// Esse código fará isso (...) e aquilo (...) // ...e quem sabe o que mais... muito; complexo; código;
Mas em um bom código, a quantidade desses comentários “explicativos” deve ser mínima. Sério, o código deve ser fácil de entender sem eles.
Existe uma ótima regra sobre isso: “se o código é tão claro que requer um comentário, então talvez deva ser reescrito”.
Às vezes é benéfico substituir um trecho de código por uma função, como aqui:
função mostrarPrimes(n) {
próximoPrime:
for (seja i = 2; i < n; i++) {
// verifica se i é um número primo
for (seja j = 2; j < i; j++) {
if (i % j == 0) continue nextPrime;
}
alerta(eu);
}
} A melhor variante, com uma função fatorada isPrime :
função mostrarPrimes(n) {
for (seja i = 2; i < n; i++) {
se (!isPrime(i)) continuar;
alerta(eu);
}
}
função éPrime(n) {
for (seja i = 2; i < n; i++) {
se (n% i == 0) retornar falso;
}
retornar verdadeiro;
}Agora podemos entender o código facilmente. A própria função se torna o comentário. Esse código é chamado de autodescritivo .
E se tivermos uma longa “folha de códigos” como esta:
// aqui adicionamos whisky
for(seja i = 0; i < 10; i++) {
deixe cair =getWhiskey();
cheiro(gota);
adicionar(gota, vidro);
}
// aqui adicionamos suco
for(seja t = 0; t < 3; t++) {
deixe tomate = getTomato();
examinar(tomate);
deixe suco = espremer(tomate);
adicionar(suco, copo);
}
// ...Então pode ser uma variante melhor refatorá-lo em funções como:
adicionarUísque(copo);
adicionarSuco(copo);
function addUísque(contêiner) {
for(seja i = 0; i < 10; i++) {
deixe cair =getWhiskey();
//...
}
}
function addJuice(contêiner) {
for(seja t = 0; t < 3; t++) {
deixe tomate = getTomato();
//...
}
}Mais uma vez, as próprias funções dizem o que está acontecendo. Não há nada a comentar. E também a estrutura do código é melhor quando dividida. Está claro o que cada função faz, o que é necessário e o que retorna.
Na realidade, não podemos evitar totalmente comentários “explicativos”. Existem algoritmos complexos. E existem “ajustes” inteligentes para fins de otimização. Mas geralmente devemos tentar manter o código simples e autodescritivo.
Portanto, comentários explicativos geralmente são ruins. Quais comentários são bons?
Descreva a arquitetura
Fornece uma visão geral de alto nível dos componentes, como eles interagem, qual é o fluxo de controle em diversas situações... Resumindo – a visão panorâmica do código. Existe uma linguagem UML especial para construir diagramas de arquitetura de alto nível que explicam o código. Definitivamente vale a pena estudar.
Parâmetros e uso da função do documento
Existe uma sintaxe especial JSDoc para documentar uma função: uso, parâmetros, valor retornado.
Por exemplo:
/**
* Retorna x elevado à enésima potência.
*
* @param {number} x O número a ser aumentado.
* @param {number} n A potência deve ser um número natural.
* @return {number} x elevado à enésima potência.
*/
função pow(x, n) {
...
}Tais comentários nos permitem entender o propósito da função e utilizá-la da maneira correta, sem olhar em seu código.
A propósito, muitos editores como o WebStorm também podem entendê-los e usá-los para fornecer preenchimento automático e verificação automática de código.
Além disso, existem ferramentas como o JSDoc 3 que podem gerar documentação HTML a partir dos comentários. Você pode ler mais informações sobre JSDoc em https://jsdoc.app.
Por que a tarefa é resolvida desta forma?
O que está escrito é importante. Mas o que não está escrito pode ser ainda mais importante para entender o que está acontecendo. Por que a tarefa é resolvida exatamente dessa maneira? O código não dá resposta.
Se existem muitas maneiras de resolver a tarefa, por que esta? Especialmente quando não é o mais óbvio.
Sem tais comentários, a seguinte situação é possível:
Você (ou seu colega) abre o código escrito há algum tempo e vê que ele está “aquém do ideal”.
Você pensa: “Quão estúpido eu era naquela época e quão mais inteligente sou agora” e reescreve usando a variante “mais óbvia e correta”.
…A vontade de reescrever foi boa. Mas no processo você vê que a solução “mais óbvia” está realmente faltando. Você até se lembra vagamente do porquê, porque já tentou há muito tempo. Você reverte para a variante correta, mas o tempo foi perdido.
Comentários que explicam a solução são muito importantes. Eles ajudam a continuar o desenvolvimento da maneira certa.
Algum recurso sutil do código? Onde eles são usados?
Se o código tiver algo sutil e contra-intuitivo, definitivamente vale a pena comentar.
Um sinal importante de um bom desenvolvedor são os comentários: sua presença e até mesmo sua ausência.
Bons comentários nos permitem manter bem o código, voltar a ele depois de um atraso e usá-lo de forma mais eficaz.
Comente isso:
Arquitetura geral, visão de alto nível.
Uso da função.
Soluções importantes, especialmente quando não são imediatamente óbvias.
Evite comentários:
Isso diz “como o código funciona” e “o que ele faz”.
Coloque-os apenas se for impossível tornar o código tão simples e autodescritivo que não os exija.
Os comentários também são usados para ferramentas de autodocumentação como JSDoc3: eles os leem e geram documentos HTML (ou documentos em outro formato).