Che cos'è il codice autocompensante e può sostituire un codice ben documentato? [chiuso]

Ho un collega che insiste sul fatto che il suo codice non ha bisogno di commenti, è "auto-documentazione".

Ho rivisto il suo codice e, sebbene sia più chiaro del codice che ho visto produrre da altri, non sono ancora d'accordo sul fatto che il codice autocompattante sia completo e utile come pure il commento e il documento documentato.

Aiutami a capire il suo punto di vista.

• Cos'è il codice auto-documentante
• Può davvero sostituire il codice ben commentato e documentato
• Ci sono situazioni in cui è meglio di un codice ben documentato e commentato
• Ci sono esempi in cui il codice non può essere auto-documentato senza commenti

Forse sono solo i miei limiti, ma non vedo come possa essere una buona pratica.

Questo non vuole essere un argomento - per favore non evidenziare i motivi per cui un codice ben commentato e documentato ha la massima priorità - ci sono molte risorse che lo dimostrano, ma non sono convincenti per il mio collega. Credo di aver bisogno di capire meglio la sua prospettiva per convincerlo altrimenti. Inizia una nuova domanda se è necessario, ma non discutere qui.

Caspita, risposta rapida! Si prega di leggere tutte le risposte esistenti e fornire commenti alle risposte piuttosto che aggiungere nuove risposte, a meno che la risposta non sia sostanzialmente diversa da ogni altra risposta qui.

Inoltre, quelli di voi che stanno discutendo contro il codice auto-documentante, questo è principalmente per aiutarmi a capire la prospettiva (cioè, gli aspetti positivi) degli evangelisti del codice auto-documentante. Mi aspetto che gli altri ti sottovalutino se non rimani sull'argomento.

Secondo me, qualsiasi codice dovrebbe essere auto-documentato. In un buon codice auto-documentato, non è necessario spiegare ogni singola riga perché ogni identificatore (variabile, metodo, classe) ha un chiaro nome semantico . Avere più commenti del necessario in realtà rende più difficile (!) Leggere il codice, quindi se il tuo collega

• scrive commenti di documentazione (Doxygen, JavaDoc, commenti XML ecc.) per ogni classe, membro, tipo e metodo AND
• commenta chiaramente eventuali parti del codice che non sono autocompattanti AND
• scrive un commento per ogni blocco di codice che spiega l'intento o cosa fa il codice a un livello di astrazione più elevato (ovvero trova tutti i file più grandi di 10 MB anziché scorrere tutti i file in una directory, verifica se la dimensione del file è maggiore di 10 MB, rendimento reso se vero )

il suo codice e la sua documentazione vanno bene, secondo me. Si noti che il codice autocertificato non significa che non ci dovrebbero essere commenti, ma solo che non dovrebbero esserci commenti non necessari. Il fatto è, tuttavia, che leggendo il codice (inclusi commenti e commenti di documentazione) si dovrebbe capire immediatamente cosa fa il codice e perché. Se il codice di "auto-documentazione" impiega più tempo a comprendere rispetto al codice commentato, non è realmente auto-documentazione.

Bene, dato che si tratta di commenti e codice, diamo un'occhiata ad alcuni codici reali. Confronta questo codice tipico:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

A questo codice auto-documentante, che mostra cosa viene fatto:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

E poi a questo codice documentato, che spiega meglio perché è stato fatto:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

E la versione finale del codice come documentazione con zero commenti necessari:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Ecco un esempio di uno stile di commento scadente:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

Nell'ultimo esempio, i commenti vengono utilizzati quando invece le variabili avrebbero dovuto essere denominate in modo descrittivo, e i risultati di un'operazione sono riepilogati quando possiamo vedere chiaramente quale sia l'operazione. Preferirei il secondo esempio auto-documentato a questo ogni giorno, e forse questo è ciò di cui parla il tuo amico quando dice un codice auto-documentato.

Direi che dipende dal contesto di ciò che stai facendo. Per me, in questo caso è probabilmente sufficiente il codice auto-documentato, ma è utile anche un commento che descriva in dettaglio la metodologia alla base di ciò che sta dietro (in questo esempio l'equazione).

Il codice stesso sarà sempre la spiegazione più aggiornata di ciò che fa il tuo codice, ma secondo me è molto difficile spiegare l' intento , che è l'aspetto più vitale dei commenti. Se è scritto correttamente, sappiamo già cosa fa il codice, dobbiamo solo sapere perché mai lo fa!

Qualcuno ha detto una volta

1) Scrivi solo commenti per il codice che è difficile da capire.
2) Cerca di non scrivere codice difficile da capire.

L'idea alla base del codice "auto-documentante" è che la logica del programma nel codice è abbastanza banale da spiegare a chiunque legga il codice non solo ciò che il codice sta facendo, ma perché lo sta facendo.

A mio avviso, l'idea del vero codice autocompensante è un mito. Il codice può dirti la logica dietro ciò che sta accadendo, ma non può spiegare perché è stato fatto in un certo modo, in particolare se esiste più di un modo per risolvere un problema. Per questo motivo da solo non può mai sostituire il codice ben commentato .

Penso che sia pertinente chiedersi se una determinata riga di codice sia auto-documentante, ma alla fine se non si capisce la struttura e la funzione di una porzione di codice, la maggior parte delle volte i commenti non saranno di aiuto. Prendi, ad esempio, la porzione di amdfan di codice "correttamente commentato":

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Questo codice va bene, ma quanto segue è ugualmente informativo nella maggior parte dei moderni sistemi software e riconosce esplicitamente che l'uso di un calcolo newtoniano è una scelta che potrebbe essere modificata qualora qualche altro paradigma fisico fosse più appropriato:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Nella mia esperienza personale, ci sono pochissime situazioni di codifica "normali" in cui hai assolutamente bisogno di commenti. Con quale frequenza finisci per implementare il tuo algoritmo, ad esempio? Fondamentalmente tutto il resto è una questione di strutturare il tuo sistema in modo che un programmatore possa comprendere le strutture in uso e le scelte che hanno spinto il sistema ad usare quelle particolari strutture.

Dimentico da dove l'ho preso, ma:

Ogni commento in un programma è come una scusa per il lettore. "Mi dispiace che il mio codice sia così opaco che non puoi capirlo guardandolo". Non ci resta che accettare che non siamo perfetti ma ci sforziamo di essere perfetti e di scusarci subito quando ne abbiamo bisogno.

Prima di tutto, è bello sapere che il codice del tuo collega è in realtà più chiaro di altri codici che hai visto. Vuol dire che probabilmente non sta usando "l'autocertificazione" come scusa per essere troppo pigro per commentare il suo codice.

Il codice auto-documentante è un codice che non richiede commenti a testo libero per un lettore informato per capire cosa sta facendo. Ad esempio, questo pezzo di codice è auto-documentante:

print "Hello, World!"

e così è questo:

factorial n = product [1..n]

e così è questo:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Ora, questa idea di "lettore informato" è molto soggettiva e situazionale. Se tu o qualcun altro hai problemi a seguire il codice del tuo collega, farebbe bene a rivalutare la sua idea di lettore informato. Un certo livello di familiarità con il linguaggio e le librerie utilizzate deve essere assunto per poter chiamare il codice autocertificazione.

La migliore argomentazione che ho visto per aver scritto "codice auto-documentante" è che evita il problema dei commenti a testo libero che non concordano con il codice così come è scritto. La migliore critica è che mentre il codice può descrivere cosa e come sta facendo da solo, non può spiegare perché qualcosa viene fatto in un certo modo.

Il codice auto-documentante è un buon esempio di "DRY" (non ripetere te stesso). Non duplicare informazioni nei commenti che sono, o possono essere, nel codice stesso.

Invece di spiegare a cosa serve una variabile, rinominare la variabile.

Piuttosto che spiegare cosa fa un breve frammento di codice, estrailo in un metodo e assegnagli un nome descrittivo (forse una versione abbreviata del testo del tuo commento).

Invece di spiegare cosa fa un test complicato, estrailo anche in un metodo e dagli un buon nome.

Eccetera.

Dopodiché si finisce con un codice che non richiede tante spiegazioni, si spiega da sé, quindi è necessario eliminare i commenti che si limitano a ripetere le informazioni nel codice.

Questo non significa che non hai alcun commento, ci sono alcune informazioni che non puoi inserire nel codice come informazioni sull'intento (il "perché"). Nel caso ideale il codice e i commenti si completano a vicenda, ciascuno aggiungendo un valore esplicativo unico senza duplicare le informazioni nell'altro.

il codice auto-documentante è una buona pratica e, se fatto correttamente, può facilmente comunicare il significato del codice senza leggere troppi commenti. soprattutto in situazioni in cui il dominio è ben compreso da tutti i membri del team.

Detto questo, i commenti possono essere molto utili per i nuovi arrivati ​​o per i tester o per generare file di documentazione / aiuto.

il codice di auto-documentazione + i commenti necessari contribuiranno notevolmente ad aiutare le persone attraverso i team.

In ordine:

• Il codice auto-documentante è un codice che esprime chiaramente le sue intenzioni al lettore.
• Non del tutto. I commenti sono sempre utili per i commenti sul perché è stata scelta una particolare strategia. Tuttavia, i commenti che spiegano cosa sta facendo una sezione di codice sono indicativi di un codice che non è sufficientemente autocompattante e potrebbe usare alcuni refactoring.
• I commenti mentono e diventano obsoleti. Il codice dice sempre che è più probabile che dica la verità.
• Non ho mai visto un caso in cui il what of code non potesse essere sufficientemente chiarito senza commenti; tuttavia, come ho detto prima, a volte è necessario / utile includere commenti sul perché .

È importante notare, tuttavia, che un vero codice di auto-documentazione richiede molta disciplina personale e di squadra. Devi imparare a programmare in modo più dichiarativo, e devi essere molto umile ed evitare un codice "intelligente" a favore di un codice così ovvio che sembra che qualcuno avrebbe potuto scriverlo.

Quando leggi un "codice auto-documentante", vedi cosa sta facendo, ma non puoi sempre indovinare perché lo sta facendo in quel modo particolare.

Ci sono tonnellate di vincoli di non programmazione come logica aziendale, sicurezza, richieste degli utenti ecc.

Quando si esegue la manutenzione, queste informazioni di backgorund diventano molto importanti.

Solo il mio pizzico di sale ...

Per uno, considera il seguente frammento:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

In questo esempio hai 5 righe di commenti per 3 righe di codice. Ancora peggio: i commenti non aggiungono nulla che non puoi vedere leggendo il codice. Se hai 10 metodi come questo, puoi ottenere la "cecità nei commenti" e non notare l'unico metodo che si discosta dallo schema.

Se ovviamente, una versione migliore sarebbe stata:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Tuttavia, per codice banale preferisco non avere commenti. L'intento e l'organizzazione generale sono meglio spiegati in un documento separato al di fuori del codice.

La differenza è tra "cosa" e "come".

• Dovresti documentare "cosa" fa una routine.
• Non dovresti documentare "come" lo fa, a meno che non si tratti di casi speciali (ad es. Fare riferimento a un documento di algoritmo specifico). Questo dovrebbe essere auto-documentato.

Una cosa che potresti voler segnalare al tuo collega è che non importa quanto sia autocompensante il suo codice, se altri approcci alternativi sono stati considerati e scartati, le informazioni andranno perse a meno che non commenti il ​​codice con quelle informazioni. A volte è altrettanto importante sapere che è stata presa in considerazione un'alternativa e perché è stata decisa e i commenti sul codice hanno più probabilità di sopravvivere nel tempo.

In una società in cui lavoravo, uno dei programmatori aveva i seguenti elementi bloccati nella parte superiore del suo monitor.

"Documenta il tuo codice come la persona che lo sostiene è un maniaco omocida che sa dove vivi."

il codice auto-documentante normalmente utilizza nomi di variabili che corrispondono esattamente a ciò che il codice sta facendo in modo che sia facile capire cosa sta succedendo

Tuttavia, tale "codice auto-documentante" non sostituirà mai i commenti. A volte il codice è troppo complesso e il codice di auto-documentazione non è sufficiente, soprattutto per quanto riguarda la manutenibilità.

Una volta avevo un professore che credeva fermamente in questa teoria. In effetti la cosa migliore che io abbia mai ricordato mentre diceva è "I commenti sono per femminucce" All'inizio
ci siamo sorpresi tutti, ma ha senso.
Tuttavia, la situazione è che anche se potresti essere in grado di capire cosa sta succedendo nel codice, ma qualcuno che ha meno esperienza potrebbe venire dietro di te e non capire cosa sta succedendo. Questo è quando i commenti diventano importanti. So molte volte che non crediamo che siano importanti ma ci sono pochissimi casi in cui i commenti non sono necessari.

Sono sorpreso che nessuno abbia dato vita a " Literate Programming ", una tecnica sviluppata nel 1981 da Donald E. Knuth di TeX e "The Art of Computer Programming".

La premessa è semplice: dal momento che il codice deve essere compreso da un essere umano e i commenti vengono semplicemente eliminati dal compilatore, perché non dare a tutti ciò di cui hanno bisogno - una descrizione testuale completa dell'intento del codice, libera dai requisiti del linguaggio di programmazione , per il lettore umano e codice puro per il compilatore.

Gli strumenti di programmazione alfabetica fanno questo dandoti un markup speciale per un documento che dice agli strumenti quale parte dovrebbe essere la fonte e che cos'è il testo. Il programma successivamente strappa le parti del codice sorgente dal documento e assembla un file di codice.

Ne ho trovato un esempio sul web: http://moonflare.com/code/select/select.nw o la versione HTML http://moonflare.com/code/select/select.html

Se riesci a trovare il libro di Knuth su di esso in una biblioteca (Donald E. Knuth, Literate Programming, Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, n. 27.) dovresti leggerlo.

Questo è un codice auto-documentante, completo di ragionamento e tutto il resto. Anche un bel documento, tutto il resto è solo commenti ben scritti :-)

Vorrei offrire un'altra prospettiva alle molte risposte valide:

Cos'è il codice sorgente? Che cos'è un linguaggio di programmazione?

Le macchine non hanno bisogno del codice sorgente. Sono felici in esecuzione di assemblaggio. I linguaggi di programmazione sono a nostro vantaggio. Non vogliamo scrivere assembly. Dobbiamo capire cosa stiamo scrivendo. La programmazione riguarda la scrittura di codice.

Dovresti essere in grado di leggere ciò che scrivi?

Il codice sorgente non è scritto in linguaggio umano. È stato provato (ad esempio FORTRAN) ma non ha completamente successo.

Il codice sorgente non può avere ambiguità. Ecco perché dobbiamo mettere più struttura al suo interno rispetto al testo. Il testo funziona solo con il contesto, che diamo per scontato quando usiamo il testo. Il contesto nel codice sorgente è sempre esploso. Pensa "usando" in C #.

La maggior parte dei linguaggi di programmazione ha ridondanza in modo che il compilatore possa catturarci quando non siamo coerenti. Altre lingue usano più inferenza e cercano di eliminare quella ridondanza.

Nomi di tipo, nomi di metodi e nomi di variabili non sono necessari per i computer. Sono usati da noi per fare riferimento. Il compilatore non capisce la semantica, che è per noi da usare.

I linguaggi di programmazione sono un ponte linguistico tra uomo e macchina. Deve essere scrivibile per noi e leggibile per loro. Le richieste secondarie sono che dovrebbe essere leggibile per noi. Se siamo bravi in ​​semantica dove consentito e bravi a strutturare il codice, il codice sorgente dovrebbe essere facile da leggere anche per noi. Il miglior codice non ha bisogno di commenti.

Ma la complessità si nasconde in ogni progetto, devi sempre decidere dove mettere la complessità e quali cammelli ingoiare. Questi sono i luoghi in cui utilizzare i commenti.

Il codice auto-documentante è una facile rinuncia al problema, che nel tempo divergono codice, commento e documentazione. Ed è un fattore disciplinante scrivere un codice chiaro (se sei così severo con te stesso).

Per me, queste sono le regole che cerco di seguire:

• Il codice dovrebbe essere il più semplice e chiaro possibile da leggere.
• I commenti dovrebbero motivare le decisioni di progettazione che ho preso, come: perché uso questo algoritmo o le limitazioni che il codice ha, come: non funziona quando ... (questo dovrebbe essere gestito in un contratto / asserzione nel codice) (di solito all'interno della funzione / procedura).
• La documentazione dovrebbe elencare l'utilizzo (chiamate convenzioni), effetti collaterali, possibili valori di ritorno. Può essere estratto dal codice usando strumenti come jDoc o xmlDoc. Di solito quindi è al di fuori della funzione / procedura, ma vicino al codice che descrive.

Ciò significa che tutti e tre i mezzi per documentare il codice vivono vicini e quindi hanno maggiori probabilità di essere cambiati quando il codice cambia, ma non si sovrappongono in ciò che esprimono.

Il vero problema con il cosiddetto codice auto-documentante è che trasmette ciò che effettivamente fa. Mentre alcuni commenti possono aiutare qualcuno a capire meglio il codice (ad es. Passaggi degli algoritmi, ecc.) È in qualche misura ridondante e dubito che convinceresti il ​​tuo pari.

Tuttavia, ciò che è veramente importante nella documentazione sono le cose che non sono direttamente evidenti dal codice: intenti sottostanti, ipotesi, impatti, limitazioni, ecc.

Essere in grado di determinare che un codice fa X da una rapida occhiata è molto più facile che essere in grado di determinare che un codice non fa Y. Deve documentare Y ...

Potresti mostrargli un esempio di un codice che ha un bell'aspetto, è ovvio, ma in realtà non copre tutte le basi dell'input, per esempio, e vedi se lo trova.

Penso che il codice auto-documentante sia un buon sostituto per i commenti. Se hai bisogno di commenti per spiegare come o perché il codice è come è, allora hai una funzione o nomi di variabili che dovrebbero essere modificati per essere più esplicativi. Può dipendere dal programmatore se colmare il deficit con un commento o rinominare alcune variabili e funzioni e rifattorizzare il codice.

In realtà non può sostituire la tua documentazione, perché la documentazione è ciò che dai agli altri per spiegare come usare il tuo sistema, piuttosto che come fa le cose.

Modifica: io (e probabilmente tutti gli altri) probabilmente dovrei avere la disposizione che un'app Digital Signal Processing (DSP) dovrebbe essere commentata molto bene. Questo principalmente perché le app DSP sono essenzialmente 2 per i loop alimentati con array di valori e aggiunge / moltiplica / etc detti valori ... per cambiare il programma si cambiano i valori in uno degli array ... sono necessari un paio di commenti per dire cosa stai facendo in quel caso;)

Quando ho scritto codice matematico, a volte ho trovato utile scrivere lunghi commenti simili a un saggio, che spiegano la matematica, le convenzioni notazionali utilizzate dal codice e come tutto si adatta. Stiamo parlando di centinaia di righe di documentazione, qui.

Cerco di rendere il mio codice il più autocompattante possibile, ma quando torno a lavorarci su dopo alcuni mesi, ho davvero bisogno di leggere la spiegazione per evitare di trarne un hash.

Ora, ovviamente, questo tipo di misura estrema non è necessaria nella maggior parte dei casi. Penso che la morale della storia sia: codice diverso richiede quantità diverse di documentazione. Un po 'di codice può essere scritto in modo così chiaro che non ha bisogno di commenti, quindi scrivilo chiaramente e non usare commenti lì!

Ma un sacco di codice ha bisogno di commenti per avere un senso, quindi scrivilo il più chiaramente possibile e quindi usa tutti i commenti di cui ha bisogno ...

Direi - come molti di voi - che per essere veramente auto-documentante, il codice deve mostrare una qualche forma di intento. Ma sono sorpreso che nessuno abbia ancora menzionato BDD - Behavior Driven Development . Parte dell'idea è che hai dei test automatici (codice) che spiegano l'intento del tuo codice, il che è così difficile da rendere evidente altrimenti.

Buona modellazione del dominio 
+ buoni nomi (variabili, metodi, classi) 
+ esempi di codice (unit test dai casi d'uso) 
= software auto-documentante 

Un paio di ragioni per cui commenti aggiuntivi oltre al codice potrebbero essere più chiari:

• Il codice che stai visualizzando è stato generato automaticamente, quindi eventuali modifiche al codice potrebbero essere bloccate la prossima volta che il progetto viene compilato
• Un'implementazione tutt'altro che semplice è stata scambiata per un guadagno in termini di prestazioni (srotolamento di un ciclo, creazione di una tabella di ricerca per un calcolo costoso, ecc.)

Sarà tutto in ciò che il team apprezza nella sua documentazione. Suggerirei di documentare il perché / l'intento invece di quanto sia importante e questo non viene sempre catturato nel codice di auto-documentazione. ottenere / impostare no questi sono ovvi - ma calcolo, recupero ecc. qualcosa del perché dovrebbe essere espresso.

Inoltre, fai attenzione alle differenze nella tua squadra se provieni da nazionalità diverse. Le differenze nella dizione possono insinuarsi nella denominazione dei metodi:

BisectionSearch

BinarySearch

BinaryChop

Questi tre metodi hanno contribuito con gli sviluppatori formati in 3 diversi continenti a fare la stessa cosa. Solo leggendo i commenti che descrivono l'algoritmo siamo stati in grado di identificare la duplicazione nella nostra libreria.

Per me leggere il codice che necessita di commenti è come leggere un testo nella lingua che non conosco. Vedo la dichiarazione e non capisco cosa fa o perché - e devo guardare i commenti. Ho letto una frase e devo cercare nel dizionario per capire cosa significa.

Di solito è facile scrivere codice che autocerchi ciò che fa. Per dirti perché lo fanno i commenti sono più adatti, ma anche qui il codice può essere migliore. Se capisci il tuo sistema ad ogni livello di astrazione, dovresti provare a organizzare il tuo codice come

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Dove il nome del metodo riflette le tue intenzioni e il corpo del metodo spiega come raggiungere il tuo obiettivo. Non puoi comunque raccontare l'intero libro nel suo titolo, quindi le principali astrazioni del tuo sistema devono ancora essere documentate, così come algoritmi complessi, contratti di metodo non banali e artefatti.

Se il codice prodotto dal tuo collega è davvero autodocumentato, fortunatamente tu e lui. Se ritieni che il codice dei tuoi colleghi abbia bisogno di commenti, è necessario. Basta aprire il posto più banale in esso, leggerlo una volta e vedere se hai capito tutto o no. Se il codice è auto-documentato, allora dovresti. In caso contrario, fai una domanda al tuo collega dopo averti dato una risposta, chiedi perché quella risposta non è stata precedentemente documentata nei commenti o nel codice. Può affermare che il codice è un auto-documento per una persona intelligente come lui, ma deve comunque rispettare gli altri membri del team - se i tuoi compiti richiedono la comprensione del suo codice e il suo codice non ti spiega tutto ciò che devi capire - deve Commenti.

La maggior parte della documentazione / dei commenti serve ad aiutare i futuri ottimizzatori / sviluppatori di codice, rendendo quindi il codice mantenibile. Molto spesso finiremmo per tornare al nostro modulo in un secondo momento per aggiungere nuove funzionalità o ottimizzare. In quel momento sarebbe più semplice capire il codice semplicemente leggendo i commenti piuttosto che passare attraverso numerosi punti di interruzione. Inoltre preferirei passare il tempo a pensare a una nuova logica piuttosto che a decifrare l'esistente.

Penso che ciò a cui potrebbe arrivare è che se i commenti spiegano cosa sta facendo il codice, dovrebbe essere riscritto per essere chiaro quale sia il suo intento. Questo è ciò che intende per auto-documentazione del codice. Spesso questo può significare semplicemente suddividere la funzione lunga in pezzi logici più piccoli con un nome di funzione descrittivo.

Ciò non significa che il codice non debba essere commentato. Significa che i commenti dovrebbero fornire un motivo per cui il codice è scritto così com'è.

Credo che dovresti sempre sforzarti di ottenere un codice autocompensante perché semplifica la lettura del codice. Tuttavia, devi anche essere pragmatico sulle cose.

Ad esempio, di solito aggiungo un commento a ogni membro della classe (per questo uso i commenti della documentazione). Descrive cosa dovrebbe fare il membro ma non come lo fa. Trovo che quando leggo il codice, in particolare il vecchio codice, questo mi aiuta a ricordare rapidamente a cosa serve il membro e trovo anche più facile che leggere il codice e risolverlo, in particolare se il flusso di codice salta un po ' .

Questa è solo la mia opinione. Conosco molte persone che lavorano senza commenti e dicono che trovano che questo non sia un problema. Tuttavia, ho chiesto a qualcuno un metodo che avevano scritto sei mesi prima e hanno dovuto riflettere per qualche minuto per dirmi esattamente cosa ha fatto. Questo non è un problema se il metodo è commentato.

Infine, devi ricordare che i commenti fanno ugualmente parte del sistema come codice. Man mano che effettui il refactoring e modifichi la funzionalità, devi anche aggiornare i tuoi commenti. Questo è un argomento contro l'uso dei commenti in quanto sono peggio che inutili se non sono corretti.