IT knowledge base
CTRL+F per cercare la tua parola chiave

Come scrivere buoni commenti sul codice: "perché", non "come"

Ciao, Habr! Presento alla vostra attenzione la traduzione dell'articolo "Scrivere buoni commenti: il perché, non il come" di Jack Franklin.
Immagine
Commentare il codice in un ambiente di programmazione è spesso considerato una perdita di tempo o un segnale che il codice può essere migliorato. Ecco una citazione dal file CONTRIBUTING.md che ho trovato su GitHub (e ci sono molti di questi esempi):

I commenti dovrebbero essere evitati. Se il tuo codice non può essere compreso senza commenti, riscrivilo per spiegarlo.

Credo che nella maggior parte dei casi tali consigli non avranno successo e saranno errati. Credo che questo approccio sia radicato nelle esperienze di apprendimento della maggior parte delle persone che hanno studiato programmazione. Quando studiavo informatica all'università (anche se questo consiglio si trova in molti corsi, non necessariamente universitari), ricordo molto bene un insegnante del primo semestre che diceva:

Ogni riga di codice dovrebbe avere un commento che spiega cosa fa. Il tuo lavoro nel corso sarà giudicato in base a questo criterio.

Quindi diciamo che sei uno studente appena sfornato che ha appena iniziato questo corso. Che cosa hai intenzione di fare? Commenta il codice, ovviamente!
// set the value from the environment variable bar
const inputValue = process.ENV.bar

// and now multiply by 2
const newValue = inputValue * 2

// now pass the value to the square function
const finalValue = square (newValue)

// this function squares the number and returns the result
const square = (x) => x * x
Le persone che dicono che i commenti sono cattivi in ​​realtà stanno pensando a commenti come questo. E hanno assolutamente ragione! Commenti come quelli sopra, che rispondono alla domanda "come?" Nella programmazione, sono completamente inutili. Tutti questi commenti non hanno aggiunto nulla al codice che non possa essere compreso dal codice stesso.

Rispondi alla domanda "perché?"

Il problema con i commenti sopra è che spiegano come . Spiega i passaggi che eseguiamo nel codice. Tali commenti sono raramente utili; il codice stesso è molto più bravo a dirti cosa fare. Dopotutto, le righe di codice sono solo istruzioni che dicono al computer come completare un'attività.
Di solito non c'è bisogno di un'abbondanza di commenti, perché puoi scrivere un codice semplice, privo di funzionalità o sfumature che gli darebbero un aspetto incomprensibile. Ma a volte sorgono situazioni in cui è impossibile scrivere codice elementare e intuitivo. Forse è un bug che deve essere aggirato. Oppure hai ereditato la felicità dagli sviluppatori del passato sotto forma di un sistema che non ti consente di risolvere il problema come vorresti. Oppure, alla fine della giornata, semplicemente non esiste un modo semplice per migliorare il tuo codice.
Una volta lavoravo in un'azienda di trasformazione. Ogni giorno eseguivamo un'enorme query SQL che selezionava i pagamenti da pagare. La query era ben ottimizzata - avevamo bisogno che fosse molto veloce - ed estremamente complessa: c'erano molti casi limite da considerare. Abbiamo cercato molto duramente di renderlo il più chiaro possibile. Tuttavia, questa richiesta non potrebbe mai essere completamente intuitiva e di facile comprensione. Conteneva semplicemente troppo codice con una serie di condizioni e logiche che potevano essere comprese solo nel contesto della nostra azienda e del modo in cui funzionava.
Volevo trovare un esempio da mostrare qui, quindi sono andato nelle terre selvagge del codice di React per trovare qualcosa. Non è necessario essere uno sviluppatore React per capirlo. Quindi, ecco il codice che vorrei evidenziare:
// Key can now be passed as a property. This is a potential source of problems
// if key is separately explicitly declared (for example, <div {... props} key ="Hi"/>
// or <div key = "Hi" {... props} /> ). Here it would be better to exclude the key passed with the properties,
// but for now we use jsxDEV in all cases except
// <div {... props} key ="Hi"/> because at the moment it is impossible to understand
// whether key is explicitly declared undefined or not.
if (maybeKey! == undefined) {
  key = '' + maybeKey
}
( E qui c'è un link su GitHub ).
Presta attenzione al codice stesso, di cui stiamo parlando:
if (maybeKey !== undefined) {
  key = '' + maybeKey
}
Non è così difficile capire cosa sta facendo. Se mayKey non è definito, impostiamo la stringa su mayKey to key. Nota: questo è un piccolo trucco JavaScript -'' + maybeKey convertirà il contenuto di MaybeKey in una stringa.
Ma qui l'intera domanda riguarda il perché . Il commento su questo codice è fantastico. Indica il problema, fornisce due esempi e spiega anche come risolvere questo problema a lungo termine e cosa stiamo facendo a breve termine.
Se vuoi dare un'occhiata a qualsiasi commento che ho lasciato nel codice che ho scritto, eccone uno (TypeScript / Closure Compiler) . Questo è un buon esempio del tipo di commenti che trovo molto preziosi.
Alla fine, qualsiasi codice può essere compreso. Dopotutto, il codice non è altro che istruzioni che dicono al computer come procedere. Il codice può creare confusione, ma non può mentire; se c'è abbastanza tempo, qualsiasi sviluppatore può esaminare il codice passo dopo passo e capire cosa sta facendo. A volte è molto più difficile capire perché lo fa. Quindi lascia ai tuoi colleghi (o a te stesso futuro tra sei mesi) un contesto sul perché e per cosa il tuo codice fa quello che fa. Sarà molto meglio.