Comentar algo é basicamente uma forma de alguém julgar ou dar uma perspectiva diferente de algo, seja em termos de bom ou ruim no processo, vamos ponderar se vamos melhorar com base nisso ou simplesmente ignorar, de acordo com os comentários que nos foi dado.

Mas, neste post, não vamos falar sobre política, mas é mais técnico em Desenvolvimento Web, e minha perspectiva é porque precisamos fazer isso enquanto escrevemos nosso código.

Em nossa discussão desta vez, veremos como é importante comentar sobre uma função que nós mesmos criamos, claro que em JavaScript. Imagine que temos uma função assim:

function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

window.location.href = `${x}://${y}`;

Qual é a explicação dos argumentos `x`e `y`? se iremos preencher `object`ou `string`talvez possamos preencher alguma entrada especial? outro usamos Typescript, o mecanismo de type data será feito pelo próprio Typescript em tempo de execução ou talvez em desenvolvimento , mas que tal usarmos JavaScript?

Sim, em JavaScript (JS), os argumentos na `setLocation`função serão exibidos pelo editor IntelliSense como `any`significando que quaisquer dados serão permitidos.

Como você pode ver basicamente, há dois problemas aqui; Computer and a Human , quando o computador lê o código continuará a rodar independentemente do nome do argumento que definimos, mas e quanto a Human ?

A função que criamos será difícil para o próximo desenvolvedor (Humano) entender, pois sem saber o que enviar para a `setLocation`função fica diferente se deixarmos um comentário

// args `x` with data type string, is a protocol
// args `y` with data type string, is a domain name
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

Vamos tentar comentar a função que criamos, de acordo com o padrão do JSDoc , vamos mudar o comentário acima para algo assim

/**
 * A function that can be executed on address bar browser
 * @param {string} x a host url
 * @param {string} y a domain url
 */
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

De fato, o IntelliSense apenas pode ajudar os usuários a determinar o que deve ser enviado nessa função quando queremos usá-la, mas não é totalmente tipado

Isso é muito útil principalmente se tivermos uma função onde devemos enviar um objeto de dados como parâmetro da função, por exemplo, temos uma função assim

/**
 * @param {object} fullName
 * @param {string} fullName.firstName your first name
 * @param {string} fullName.lastName your last name
 */
function overwriteData(fullName) {
  return {
    firstName: "Adib",
    lastName: "Firman",
    ...fullName
  };
}

Como sempre , o IntelliSense nos dará uma dica, e você sabe que o mais interessante para essa abordagem é

Na figura acima vamos inserir os dados de acordo com as instruções do IntelliSense claro que teremos uma dica do nosso editor, interessante né?

A próxima pergunta é, devemos comentar todas as funções que criamos? Claro que não, um exemplo de uma função como esta

const sum = (firstNum, secondNum) => firstNum + secondNum;

Conclusão

Faça alguns comentários sobre nossa função, dependendo de como ela será usada, os parâmetros fornecidos são muito complexos ? ou é legível a partir da função de nomenclatura e dos argumentos criados?

Mas se você acha que a função precisa ser comentada, melhor, porque é para facilitar a manutenção do próximo desenvolvedor (Humano).

Obrigada.