Il modo migliore per scrivere commenti nel codice [chiuso]

Panoramica di cosa tratta il codice. Potrebbe essere ovvio quando lo scrivi, ma non due anni dopo, quindi annota quando questo codice viene utilizzato nell'applicazione, perché viene usato e così via. Come "questo codice gestisce la situazione in cui un utente compila un modulo che si lamenta dei pacchetti restituiti persi nel post". Risponde alla domanda "a cosa serve questo codice?"

Se non è ovvio, una panoramica di alto livello su come funziona il codice.

Commenti nei file di intestazione (o nei luoghi in cui vengono automaticamente estratti) in modo che, per ogni funzione pubblica, un lettore possa sapere cosa fa e perché dovrebbe essere chiamato senza fare riferimento al codice sorgente.

Soprattutto per le funzioni virtuali: Commenti nei file di intestazione che cosa dovrebbe fare questa funzione, incluse le sostituzioni. Per le funzioni non virtuali i commenti sono una comodità, salvandomi dalla lettura del codice sorgente. Per le funzioni virtuali, non c'è il codice sorgente .

Commenti che dicono ad altri sviluppatori quando fai qualcosa che sembra strano. Ci sono posti in cui il mio codice contiene alcune righe che sembrano assurdità assolute, e poi c'è un commento "Funziona attorno a un bug nella libreria XYZ".

Commenti che spiegano cosa fa il codice in termini di problema risolto. Come "trovare tutti i clienti che hanno acquistato articoli per un valore inferiore a $ 100 nell'ultimo anno e fatto più di tre ritorni" - questo potrebbe non essere ovvio dal codice.

"Abbiamo un array, iterate su di esso" come un commento per il codice che itera su un array non ha senso. Posso vedere che stai iterando, non ho bisogno di un commento per questo. Dimmi cosa sta effettivamente facendo l'iterazione.

Nessuno dei due. I commenti non dovrebbero descrivere cosa fa il codice (allo stesso livello di astrazione del codice stesso), ma solo perché fa qualcosa

Non prenderlo troppo alla lettera, questa è una linea guida, se scrivi un breve riassunto che farà un pezzo di codice più lungo, ciò potrebbe essere accettabile. Tuttavia, i commenti che descrivono cose ovvie come "questa è un'iterazione" dovrebbero essere evitati, non rendono il codice più leggibile o comprensibile, aggiungono solo confusione e violano il principio SECCO.

I commenti che scrivi vanno bene per il codice dimostrativo quando si insegna una nuova lingua ai principianti. Sono l'equivalente di "Vedi Jane run, Run, Jane, run!"

Ma in tutte le altre impostazioni non sono appropriati. Ogni programmatore abituale sarebbe solo perplesso, pensando "Eh? Perché me lo stai dicendo quando è già del tutto ovvio cosa sta succedendo? C'è qualcosa di non ovvio che mi manca?"

Un romanzo autore non scrive "Jane lasciò l'edificio e camminò per la strada, sistemando sistematicamente un piede davanti all'altro." Avrebbe scritto "Jane andò al grande magazzino", o anche "quando Jane arrivò al grande magazzino, lei ..." o anche solo "Avendo finito con i suoi acquisti, Jane si rilassò ..."

Allo stesso modo, un programmatore professionista non scriverebbe

// Iterate over the array
for(int x: ai) { ...

ma al massimo

// notify all observers
for(int x: ai) { ...

o anche solo

notifyObservers()

dove il codice reale è nascosto in una subroutine con un nome significativo.

I commenti servono per comunicare qualsiasi informazione ai futuri sviluppatori che utilizzano o mantengono il codice, il che non è ovvio dalla lettura del codice.

Quando scrivi commenti, considera le situazioni che si presentano ad un nuovo sviluppatore che non ha familiarità con il tuo codice e la tua mentalità attuale.

Mentre scrivi il codice, di solito ti stai divertendo con un sacco di palle in testa, cercando di evitare potenziali insidie; e i tuoi commenti dovrebbero riflettere le cose che stai manipolando, perché è più probabile che siano informazioni che ogni sviluppatore futuro dovrà anche conoscere per evitare di commettere errori. Ad esempio:

// A user could potentially type an invalid username here but we can't
// validate it yet because we need to support the legacy login format.

o

// We don't know whether the server is available yet, but we don't care
// until the user does something which involves a message to the server.

o

// Always use the FooFactory for creating Foo objects because it guarantees
// they will be initialised using the correct Config.

o

// This calculation is only an approximation until the customer can 
// supply us with the correct logic, so we know it's wrong, but the
// customer confirmed they are happy with it as an interim measure. 

o

// HACK: this function fixed a critical fault identified while on XYZ customer site.  
// This is currently in use by XYZ, it must be refactored into a generic solution ASAP.
// see ticket #12345 in the bugtracking system.

o

// This function may fail if VehicleType==Train, but there are currently no 
// documented requirements or data for Trains, so there's no way to reliably test it.

Quindi, quando cerchi di decidere quale tipo di commenti inserire nel tuo codice, fai diversi passi indietro dal codice stesso e pensa a tutti i problemi che hai dovuto affrontare, alle ipotesi che hai fatto, ai compromessi che hai fatto , ecc.

I commenti dovrebbero essere una motivazione che cattura "Perché ho scritto questo codice in questo modo particolare in questo particolare momento?". La realtà è che il codice solitamente non è mai 'finito' , il codice tende ad evolversi costantemente, tende ad essere limitato da problemi del mondo reale (scadenze, richieste dei clienti, budget, ecc.). quindi avrà sempre verruche e imperfezioni che vanno oltre il controllo dello sviluppatore.

I tuoi commenti sono il posto migliore per documentare queste cose - evita di scrivere lunghi saggi, limitati a inserire la quantità minima di informazioni che potrebbero avvisare i futuri sviluppatori di non commettere errori, o anche solo far loro sapere che hai già considerato il vantaggi / limitazioni della soluzione (o anche se hai riscontrato potenziali problemi con il codice esistente di qualcun altro e non sono stato in grado di risolverlo).

Penso che la risposta per il tuo esempio specifico non sia né l'una né l'altra. I commenti non dovrebbero spiegare cosa fa il codice. Il CODICE dovrebbe spiegare cosa fa il codice. I commenti non dovrebbero nemmeno spiegare PERCHÉ lo fa, che dovrebbe essere ovvio anche con una minima conoscenza di dominio o con conoscenze tecniche.

Questa seconda parte è difficile a volte però. A volte trovi qualche bug oscuro o una stranezza davvero strana in qualche framework che stai usando. Il "codice ovviamente migliore" potrebbe effettivamente essere peggio, rispetto all'attuale codice dall'aspetto strano, e in quei casi è ovviamente OK fare un'eccezione e aggiungere un commento che spieghi la situazione.

Tuttavia, questo dovrebbe essere considerato un fallimento. È qualcosa da evitare, perché come altri hanno fatto riferimento, i commenti sono per lo più ridondanti. I MOLOSAMENTE raramente danno davvero alcun valore. Ma la violazione di DRY non è nemmeno la parte peggiore. La parte peggiore dei commenti è che non sono codice, quindi non vengono eseguiti e quindi il lettore non ha alcuna prova che il commento abbia qualcosa a che fare con la realtà.

I commenti invecchiano, hanno degli errori, rimangono orfani, l'autore potrebbe sbagliarsi, ecc. Sono notoriamente ingannevoli. Anche se vedi un commento che dice "questo blocco di codice fa X", non puoi VERAMENTE fidarti che lo faccia X senza guardarlo.

Se ritieni che la struttura algoritmica del tuo codice sia difficile da vedere a colpo d'occhio, la soluzione non è aggiungere 20 commenti. È per ristrutturare / rifattorizzare il codice in modo che sia separato in piccole unità logiche concise con buoni nomi di metodi. Usa i modelli che tutti impariamo. Incapsulare le cose Disegna una buona architettura, non coprirne una brutta attaccando post-it dappertutto.

EDIT: giusto per chiarire dato che alcune persone sembrano aver interpretato male: non sto dicendo che non dovresti mai usare commenti. Sto dicendo che davvero non dovresti volerlo perché portano molti problemi. Sto dicendo che a volte devi, ma dovresti provare a trovare una soluzione migliore.