Quanto commento è meglio per la codifica? [duplicare]

Dico sempre ai miei sviluppatori di commentare "Perché?" non il "Cosa?" o "Come?".

Posso sempre capire cosa sta facendo qualcosa dal codice. Ma è molto più difficile capire perché è stato fatto.

Così tante volte vado a correggere un bug e trovo che il codice che causa il bug sembra essere intenzionale. Devo quindi preoccuparmi di quale altro comportamento (attualmente invocato) si interromperà quando correggo questo bug.

Un commento che dice che il codice non mi è molto utile a quel punto, ma un commento che dice perché il codice è molto utile.

Per i manutentori (che è davvero per chi inseriamo i commenti), i commenti " perché " sono davvero utili.

UPDATE:
Alcuni dicono anche di commentare "Cosa / come" sul tuo codice complicato. (Cose che sarebbe difficile da capire.) Sono d'accordo con questo finché non puoi rendere il codice "non complicato" e comunque soddisfare i requisiti.

Un esempio di questo è se si debba rendere più difficile la lettura del codice per soddisfare i requisiti di prestazione dell'applicazione.

UPDATE II:
I "commenti" possono facilmente atrofizzarsi man mano che i manutentori cambiano il codice e non i commenti. Questo è il motivo per cui copiose quantità di commenti possono essere una brutta cosa.

"Perché" i commenti di solito non si atrofizzano perché anche se la necessità / ragione di qualche codice / funzionalità cambia, il commento "perché" dice ancora al manutentore qual è la ragione al momento della codifica (e porta a sapere se è ancora necessario)

La mia esperienza è che ci sono 2 tipi di commenti che sono utili. Il primo tipo è essenziale ed è quando è necessario spiegare lo scopo di qualcosa che sembra del tutto inutile. Ad esempio, se c'è un errore in una libreria che richiede una soluzione non intuitiva. Il secondo tipo è commentando che spiega come usare le cose. Queste sono fondamentalmente istruzioni. Questi sono generalmente di alto livello e non spiegano come funzionano le cose, ma piuttosto quale uso hanno e cosa è richiesto all'utente.

Non penso che sia utile scrivere lunghi commenti su come funziona il codice o spiegare un codice banale (ad esempio "getName: ottiene il nome"). Una cosa che ho imparato nel corso degli anni è che non ci si può fidare di questo tipo di commenti, devi leggere il codice e seguirlo. Nel migliore dei casi ti dice cosa l'autore pensava che il codice avrebbe fatto e nel peggiore dei casi, è completamente obsoleto e sbagliato. Quando lavori in una squadra, vedrai spesso commenti scritti per la prima versione del codice e mai aggiornati. Non mi preoccupo nemmeno di guardare questo tipo di cose. Questo vale anche per i documenti di design. Se ritieni che il codice sia difficile da capire, dovresti rifattarlo. Una cosa importante è usare nomi descrittivi e significativi. Anche questo può essere preso troppo lontano. Conosco un ragazzo che nomina le cose con frasi quasi complete ed è troppo rumore e rende il codice difficile da leggere.

P.S. Mi sono ricordato un paio di altri tipi di commenti che sono utili. Quando hai un blocco di codice vuoto (diciamo che vuoi nascondere il costruttore predefinito in Java) dovresti aggiungere un commento che mostri che è vuoto. Alcuni sviluppatori e gli strumenti di qualità del codice si agitano davvero sui blocchi di codice vuoti. Se hai bisogno / vuoi tornare a qualcosa più tardi, usa i commenti di TODO. Ti aiutano a ricordare e far sapere agli altri che c'è qualcosa di incompiuto.

Quanti punti dovrebbe avere un essere umano nel loro corpo? Idealmente nessuno - così avanzato come la tecnologia medica è diventato, i buchi nella pelle per infilare oggetti estranei nel tuo corpo non possono essere così sani, e non sono molto comodi. Ma se hai una ferita aperta, vorrai comunque cucirla (o usare qualche altro metodo per chiuderla). Non rifiuterai i punti solo perché normalmente non li vuoi nel tuo corpo. Quindi, per rispondere alla mia domanda, gli umani dovrebbero avere nel loro corpo la quantità minima di punti necessari per fermarli dal sanguinamento alla morte.

I commenti nel codice sono simili - dovresti avere la minima quantità di commenti richiesti per capire e usare il codice. Se altri sviluppatori (che includono tu anche se ritorni al tuo codice dopo non averlo toccato per 6 mesi) non riescono a capire il tuo codice perché non è stato commentato a sufficienza - che hai troppo poco commenti . Se hai troppi commenti, per definizione hai commenti che non sono necessari per capire e / o usare il codice. Questi commenti stanno sprecando il tuo tempo per scriverli, sprecando il tempo degli utenti per doverli leggere e sprecare il tempo dei maintainer per doverli mantenere (o rischiare che i commenti non siano sincronizzati dal codice).

A questo punto va notato che se hai qualche strumento che genera aiuto dai tuoi commenti (sia che si tratti di uno strumento come javadoc che genera file HTML o il tooltip di una bolla IDE), supponi sempre che gli utenti delle tue classi e funzioni guarda cosa genera lo strumento e documenta in modo tale che saranno in grado di capire cosa fa il codice solo dall'output dello strumento.

Come per il codice che si documenta da solo - può effettivamente salvare commenti ridondanti, ma non è questo il punto di questa pratica. Trovo che, come regola generale, se puoi refactoring il codice in modo che si documenterà il risultato sarà un codice migliore. Ad esempio, considera questa semplice funzione Python per calcolare la distanza tra due punti:

def distance(x1, y1, x2, y2):
    return sqrt(  # root of the sum of the squares
        (x2 - x1) * (x2 - x1) +  # distance on the X axis
        (y2 - y1) * (y2 - y1))  # distance on the Y axis

(In questo caso il codice è semplice, e dovrebbe essere comprensibile anche senza i commenti - ma per il gusto degli argomenti assumiamo che non lo sia)

Ora facciamo il refactoring per documentarsi:

def distance(x1, y1, x2, y2):
    delta_x = x2 - x1
    delta_x_squared = delta_x * delta_x

    delta_y = y2 - y1
    delta_y_squared = delta_y * delta_y

    sum_of_squares = delta_x_squared + delta_y_squared

    return sqrt(sum_of_squares)

Questo è un codice molto semplice che documenta la tecnica stessa - invece di commentare ciò che fa ogni singola parte dell'espressione, l'ho messo in una variabile e gli ho dato un nome che lo spiega. Suppongo che questo si traduca in un codice più gestibile, perché se non funziona correttamente è possibile eseguirlo in un debugger e osservare il risultato di ogni parte del calcolo (o semplicemente stamparlo su STDOUT). Non resto che ogni sub-espressione abbia bisogno di questo trattamento - ma se una sotto-espressione non è abbastanza ovvia da essere documentata, è anche abbastanza non banale da sbagliare.

Ancora, come i punti - se hai davvero bisogno di commenti dovresti inserire dei commenti. Nessuna pratica migliore dovrebbe essere seguita alla lettera a tutti i costi (non è possibile farlo con tutti loro comunque - sono in conflitto troppo), e questo include il codice-dovrebbe-documentarsi. Refactoring del codice per documentarsi può causare una mostruosità (o perché hai sbagliato o perché non può essere fatto bene), o semplicemente essere completamente annullabile. L'ideale che il codice dovrebbe documentarsi non dovrebbe mai essere usato come scusa per il codice che non può essere compreso a causa della mancanza di commenti. Può sembrare sciocco, dal momento che sconfigge lo scopo di questa regola, ma è più spesso di quanto dovrebbe comportare ciecamente le migliori pratiche.

//Thoughts about code with too many comments
//I will give a reason to avoid using too many comments
//My reasoning will relate to the size of the source code
//I will also mention the need to update comments
//http://programmers.stackexchange.com/questions/317055/how-much-commenting-is-better-for-coding
// - user2023861
Here are my thoughts about code with too many comments

//checking if comments restate code
If you include comments that restate what your code is doing 

    //The size of the code will double
    Your code will double in size

    //code changes require comment changes
    When your code changes, your comments will also need to change

    //the code maintainer won't trust the comments and will ignore them
    This breaks the trust that a code maintainer may have in the comments

//The end of my hypotheical scenario
End if

Sono d'accordo con la risposta di Vaccano. Se solo aggiungessi che qualcuno arriverà al tuo codice dopo che te ne sei andato, è probabile che lo cambierà e probabilmente lo spezzerà.

Quindi cerco di lasciare istruzioni a coloro che verranno dopo di me. Perché ho fatto quello che ho fatto e non qualcos'altro, e come apportare modifiche che posso prevedere che potrebbero essere necessarie in futuro. Quei programmatori certamente lo apprezzano.

In realtà "Quanto commento è meglio [...]" è la domanda sbagliata. La domanda giusta è "Quali commenti sono positivi e quali commenti sono negativi?"

In realtà non si tratta di commentare di meno, di commentare di più, o addirittura di trovare un equilibrio, si tratta di includere tutti i commenti che sono utili per i futuri lettori e di tralasciare tutti quelli che aggiungono solo rumore al codice.

Quindi, come possiamo definire un commento negativo? Lo metterei in questo modo: un commento è negativo se la scrittura / mantenimento / lettura richiede più tempo rispetto al suo contenuto consente di risparmiare tempo. Questo è sempre il caso se il commento rientra in una di queste categorie:

• Il commento ripete ciò che è ovvio dal codice, dal nome di una variabile o dal nome di una funzione. Il codice esiste comunque e la lettura del codice produce l'informazione alla stessa velocità di lettura del commento. I commenti in stile Doxygen sono un famigerato criminale di questa regola, motivo per cui personalmente non mi piacciono questi strumenti. Ma non fraintendetemi, alcuni commenti in stile Doxygen sono buoni. Non è lo stile che conta, è il loro contenuto!

• Il commento non è sincronizzato con il codice. È chiaro il motivo per cui tali commenti dovrebbero essere cancellati a vista, sono decisamente fuorvianti. Sfortunatamente, è spesso abbastanza difficile rendersi conto che un commento è andato fuori sincrono perché devi escludere la possibilità che tu non abbia capito cosa significa. Il che rende i commenti fuori sincrono solo più costosi.

D'altra parte, i commenti positivi includono informazioni che non sono trasmesse dal codice stesso. E più velocemente ottengono il loro punto di vista, meglio sono. Gli esempi includono:

• Commenti che descrivono i modelli di utilizzo previsto per il codice.

• Commenti che descrivono strutture architettoniche troppo grandi per dedurre rapidamente dal codice stesso.

• Commenti che descrivono il motivo per cui il codice fa le cose come fa loro. Ad esempio, se il codice funziona attorno a un bug del compilatore, non va bene se ogni persona che tocca il codice prima rifiuta il cruft dal codice, solo per rendersi conto che questo cruft era necessario per evitare l'attivazione di un internal compiler error .

• Commenti che descrivono quali possibili implementazioni sono state scelte non e perché non sono state scelte. Questi possono risparmiare un po 'di tempo per i futuri refactorer che alla fine arriverebbero alle stesse conclusioni del programmatore originale. Purtroppo, questi commenti sono raramente visibili, e io sono colpevole di ometterli come chiunque altro ...

Come puoi vedere, puoi facilmente scrivere un sacco di commenti molto preziosi, o commentare molto scarsamente e comunque essere meno utile. È la qualità dei commenti che conta, non la loro quantità.