4. COMENTÁRIOS

Este é um tema transversal a qualquer linguagem de programação. É também um dos temas mais sensíveis e que levam sempre a alguma discussão entre os programadores.

Os comentários em JavaScript podem ser adicionados de várias maneiras. Uma maneira comum é usar a sintaxe '//', que indica que o restante da linha é um comentário e não será executado como código. Por exemplo:

// Este é um comentário em JavaScript
let x = 10;

Os comentários também podem ser escritos usando a sintaxe /* */, que permite que se adicione comentários num grupo de linhas. Por exemplo:

/*
Este é um comentário em JavaScript
que abrange várias linhas.
*/
let x = 10;

Os comentários não são código, não são interpretados pela máquina, podem ocupar muito espaço mas também ajudar na interpretação do código, principalmente quando existem vários programadores, em fases diferentes, a trabalhar no mesmo projeto. Outras razões pelas quais os comentários podem dar jeito, são por exemplo, em novos desenvolvimentos ou após a deteção de erros no código. Se um programador incluir um comentário a descrever que tipo de funcionalidades deve acrescentar numa determinada zona do código, mais tarde, esse comentários pode vir a ser útil para confirmar se o código está ou não a fazer o pretendido, ou após a deteção de algum erro, poder também ser usado para marcar a zona ou zonas do código que precisam ser corrigidos ou analisadas. De notar que este tipo de comentários deve ser apagado antes de ser enviado o código para produção.

No entanto, é importante também lembrar que comentários mal escritos podem ser prejudiciais. Comentários desnecessários ou demasiado evidentes, ou aqueles que não tragam uma razão forte para a sua existência, podem dificultar a leitura e compreensão desse mesmo código. Por outro lado, se os comentários que perdurem no código não forem por vezes atualizados quando esse código é modificado, podem tornar-se obsoletos.

O próprio código deve ser sempre auto explicativo mas se houver, por exemplo, um link associado a uma variável que só é usado em ambientes de desenvolvimento/produção essa indicação deve estar identificada, ou se houver uma função com cálculos ou regras que sejam muito especificas, esse código deverá ter breves comentários a explicar o intuito dessa função e/ou dessas regras.

Maus exemplos:

const userNames = ['Ana', 'Maria', 'Paulo']; // lista de utilizadores 
const usersSize = users.length // tamanho do array de utilizadores
let x = 10; // define a variável x com o valor 10

Bons exemplos:

const serverUrl = 'admin@devcode.general.com'; // só funciona no ambiente de desenvolvimento.

// cálcula a raiz quadrada de um número através do método de Newton-Raphson
function raizQuadrada(n) {
  var x = n;
  var y = 1;
  var e = 0.000001; // precisão desejada para a diferença entre x e y

  // itera o cálculo de x e y até que a diferença entre eles seja menor do que a precisão desejada
  while (x - y > e) {
    x = (x + y) / 2;
    y = n / x;
  }

  return x;
}

Explicação:

Não faz sentido comentar uma variável tão simples como "userNames" ou "usersSize". O nome dessa variável desde que tenha sido bem escolhida (ver primeiro artigo desta série) é auto explicativa e esses comentários apenas vão encher o código e torna-lo confuso. Ou no caso da linha que define a variável "x" já indica claramente o que se está a fazer. Além disso, o código é simples o suficiente para que qualquer pessoa possa entender sem um comentário adicional.

No caso do "serverUrl", e embora haja também maneiras mais eficientes de definir diferentes ambientes, este ao existir no código, seria um bom exemplo de uma descrição que poderia estar comentada para ser mais claro que aquele link só é usado em máquinas de desenvolvimento.

Por último, na última função, o comentário também pode ser importante para esclarecer o método de Newton-Raphson, que é usado para calcular a raiz quadrada de um número. Esse método pode ser um pouco complicado de entender para aqueles que não estão familiarizados com o assunto, daí os comentários ajudarem a explicar como ele funciona.

Em resumo, usar comentários pode ser importante porque pode ajudar a explicar o que o código faz ou o que é pretendido fazer, pode fornecer documentação útil bem como ajudar a detetar futuros problemas. No entanto, é importante escrever comentários claros e concisos, que realmente ajudem o programador a entender o código. Comentários mal escritos podem prejudicar a legibilidade do código e torná-lo difícil de manter.

Artigos Relacionados: