Commentare qualcosa è fondamentalmente un modo per qualcuno di giudicare o dare una prospettiva diversa di qualcosa, che sia in termini di bene o male nel processo, considereremo se miglioreremo sulla base di ciò o semplicemente lo ignoreremo, secondo i commenti che ci è stato dato.

Ma, in questo post, non parleremo di politica, ma è più tecnico sullo sviluppo Web, e la mia prospettiva è perché dobbiamo farlo durante la scrittura del nostro codice.

Nella nostra discussione questa volta, vedremo quanto sia importante commentare una funzione che abbiamo creato noi stessi, ovviamente in JavaScript. Immaginiamo di avere una funzione come questa:

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

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

Qual è la spiegazione degli argomenti `x`e `y`? se compileremo `object`o `string`forse possiamo inserire qualche input speciale? un altro usiamo Typescript, il meccanismo dei dati di tipo verrà eseguito da Typescript stesso in fase di esecuzione o forse in fase di sviluppo , ma che ne dici di utilizzare JavaScript?

Sì, in JavaScript (JS) gli argomenti nella `setLocation`funzione verranno visualizzati dall'editor IntelliSense nel `any`senso che qualunque sia il dato sarà consentito.

Come puoi vedere fondamentalmente, qui c'è il problema di due; Computer and a Human , quando il computer legge il codice continuerà a funzionare indipendentemente dal nome dell'argomento che abbiamo impostato, ma che dire di un Human ?

La funzione che creiamo sarà difficile da capire per il prossimo sviluppatore (umano), perché senza sapere cosa inviare alla `setLocation`funzione, è diverso se lasciamo un commento

// 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}`;
}

Proveremo a commentare la funzione che abbiamo creato, secondo lo standard di JSDoc , cambieremo il commento sopra in qualcosa del genere

/**
 * 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}`;
}

In effetti, IntelliSense può solo aiutare gli utenti a determinare cosa deve essere inviato in quella funzione quando vogliamo usarla, ma non è totalmente digitato strict

Questo è molto utile soprattutto se abbiamo una funzione in cui dovremmo inviare un oggetto dati come parametro della funzione, ad esempio, abbiamo una funzione come questa

/**
 * @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
  };
}

Allo stesso modo il solito IntelliSense ci darà un suggerimento, e sai che il più interessante per questo approccio è

Nell'immagine sopra inseriremo i dati secondo le istruzioni di IntelliSense , ovviamente riceveremo un suggerimento dal nostro editor, interessante, vero?

La domanda successiva è: dovremmo commentare tutte le funzioni che abbiamo creato? Certo che no, un esempio di una funzione come questa

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

Conclusione

Metti alcuni commenti sulla nostra funzione, a seconda di come verrà utilizzata i parametri dati sono molto complessi ? o è leggibile dalla funzione di denominazione e dagli argomenti creati?

Ma se ritieni che la funzione debba ricevere un commento, è meglio, perché è per facilitarne la manutenzione da parte del prossimo sviluppatore (umano).

Grazie.