Preferisco scrivere codice di auto-documentazione. Una guida per questo è Pulisci codice .

Questo ovviamente non significa che non si dovrebbero mai usare commenti - hanno il loro ruolo, ma IMHO dovresti usarli con attenzione. Questa mia precedente risposta su SO spiega i miei pensieri sull'argomento in modo più dettagliato.

Ovviamente, come ha osservato @Niphra, vale sempre la pena ricontrollare che ciò che ritengo sia pulito è comprensibile agli altri. Tuttavia, anche questa è una questione di pratica. Tornando all'università, ho scritto pezzi di codice criptici semplicemente a causa dell'uso di nomi strani e divertenti per tutte le entità del codice, secondo il mio capriccio. Fino a quando il mio insegnante ha rifiutato uno dei miei incarichi, sottolineando educatamente che non riusciva a capire quale modulo fosse il principale :-) Questa è stata una buona lezione, quindi ho cercato di concentrarmi sulla scrittura di codice sempre più leggibile da allora. Oggigiorno difficilmente riesco a lamentarmi dei compagni di squadra.

Non dovresti documentare cosa sta facendo il codice, ma dovresti documentare perché lo sta facendo.

Nessun numero di trucchi di denominazione esporrà il perché e il percome, quindi devi aggiungere commenti per spiegare lo scopo dei vari bit di codice.

Tutti gli altri commenti possono tranquillamente essere eliminati.

In realtà non credo nel codice auto-descrittivo codice più leggibile e codice meno leggibile , a seconda della lingua , la tua conoscenza di esso (come l'autore originale), la conoscenza del ragazzo che la legge e la funzione del codice. Ma no, ancora ... dovrebbe essere descritto con un breve commento.

Ciò che mi è chiaro ora, che sono in quell'area di pensiero probabilmente non mi sarà chiaro in un anno, quando sto pensando a qualcosa di completamente diverso e che devo usare questa parte del codice di nuovo.

Quindi, commenta il tuo codice. Ovviamente non tutte le righe (cieli, no) ovviamente, ma inseriamo alcune righe di commento sopra una funzione / subroutine / modulo , o una parte particolarmente complessa e diciamo in breve cosa fa. Ti ringrazierai tra un anno o due.

Fortunatamente, entrambi i campi su questa discussione sono rappresentati qui, e sono stati menzionati argomenti pro e contro per entrambi.

Credo che entrambi i campi abbiano argomenti sovrapposti, e in realtà sono d'accordo sulla maggior parte di essi, solo il modo in cui ottenerli è un po 'diverso.

Argomenti sovrapposti

• Il codice dovrebbe essere leggibile.
• I commenti non dovrebbero dire esattamente la stessa cosa del codice, ma forniscono ulteriori informazioni ove necessario.
• Tutti i nomi di variabili / funzioni dovrebbero essere studiati per dare una buona rappresentazione di ciò che sono / fanno.
• Il codice duplicato deve essere impedito.

Ora, la differenza principale è quanto peso viene messo su alcuni di questi argomenti.

Codice auto-descrittivo

• I commenti possono diventare obsoleti, quindi riduci al minimo l'utilizzo, in quanto i commenti errati sono peggio dei commenti.
• I commenti sono una duplicazione del codice. Tutto ciò che può essere scritto nel codice, dovrebbe essere scritto nel codice.

Altri commenti

• I commenti sono più leggibili del codice. È semplice descrivere l'inglese in modo semplice.

• Il codice semplice spesso causa ambiguità che deve essere comunque commentata. Cercando di descriverlo nel codice, i risultati sono nomi troppo lunghi. Inoltre, ti trovi costantemente di fronte a queste informazioni "extra" che ti servono solo la prima volta che lo incontri.

Credo che entrambi i campi abbiano argomenti molto validi, ma non dovresti seguire freneticamente un campo solo perché risolve un problema.

Per dimostrare, nel libro Pulisci codice , il codice è suddiviso in numerosi metodi più piccoli che vengono chiamati solo una volta. I metodi sono creati per il solo motivo per documentare il codice (e TDD più semplice). Ciò risulta in Funzione Hell . Il codice è meno leggibile di quanto non fosse in origine e, nonostante il refactoring, non è stato previsto alcun pensiero per incapsulare il codice riutilizzabile.

D'altra parte, spesso vedi le API in cui ogni funzione viene commentata, solo perché i commenti sono buoni. Le cose che avrebbero dovuto essere commentate ancora non lo sono.

"Mi dispiace ma è quel ragazzo."

Mi chiedo perché non gli piaccia commentare: P

Seriamente, la codifica è troppo di un'arte che si potrebbe veramente fare una dichiarazione così radicale. A volte hai bisogno di commenti, a volte più e meglio chiamate funzioni. Di solito entrambi.

Cerca la programmazione alfabetica come stile estremo.

Bene, devi anche ricordare qualcosa che è ovvio o "auto-documentante" per te, potrebbe non essere per qualcun altro ... Forse qualcuno con meno comprensione di certe funzioni. Quindi commento praticamente tutto.

Commenti e il codice pulito auto-documentato sono diversi. Il codice è incentrato su come fare le cose. E i commenti dovrebbero riguardare la parte perché , che non può essere spiegata nel codice, qualunque sia la tua lingua. Inoltre, se la tua lingua è molto limitata e non hai contratti, non hai specifiche statiche e nemmeno asserzioni, i commenti dovrebbero coprire i problemi di confine del tuo codice.

Risposta breve, migliore e corretta

L'idea che il "codice auto-documentato" ben scritto sia tutto ciò che serve è un anti-pattern e dovrebbe morire, anche quando fa eccezioni per i commenti che spiegano "perché". È un mito che tu possa sempre scrivere tutto il codice per qualsiasi algoritmo abbastanza chiaro da permettere a qualsiasi programmatore di guardarlo e ottenerlo (o che non richiederà il refactoring o il tempo organizzativo che non hai). Ancora più importante, il più delle volte, i programmatori che pensano scrivono codice chiaro no.

Una risposta molto migliore di commenti dovrebbe essere usata solo per spiegare "perché" è che i commenti dovrebbero:

• spiega "perché" (ovviamente)
• spiega "cosa" su singole righe solo quando il codice è complesso o lo scopo non è chiaro e non può essere o non vale la pena di semplificare ulteriormente
• spiega "cosa" per blocchi di codice per accelerare la comprensione e individuare ciò di cui hai bisogno

La spiegazione per eseguirne il backup

La gente pensa erroneamente che l'unica ragione per cui le persone usano i commenti è spiegare cosa significa una riga di codice. La verità è un grande scopo di commentare il codice è quello di renderlo più veloce per dare un'occhiata al tuo codice e trovare quello che stai cercando. Quando torno a leggere più tardi o leggo il codice di qualcun altro, certo, posso leggere e capire una sezione di codice ben scritto - ma non è più facile e veloce leggere il commento in alto che dice cosa fa quella sezione di codice e saltalo del tutto se non è quello che sto cercando? Perché starsene lì seduto e capire del codice, anche se è ben scritto, se puoi dare un'occhiata a un paio di commenti e capire un'intera funzione? Ecco perché utilizziamo nomi descrittivi per le funzioni - nessuno dice che non è necessario utilizzare un nome descrittivo per la mia funzione perché qualcuno può semplicemente guardare attraverso il mio codice scritto per vedere cosa fa.

Ad esempio, se guardo attraverso la funzione di qualcun altro, è più facile andare riga per riga attraverso il codice per vedere cosa sta facendo o dare un'occhiata a tre commenti ben scritti in tutta la funzione per vedere esattamente qual è la funzione fare e dove lo sta facendo?

Un altro anti-pattern è l'uso eccessivo di funzioni per commentare il tuo codice. Le funzioni ben definite sono una parte importante della documentazione del codice, ma a volte i programmatori separano 2-3 righe di codice che non verranno mai utilizzate da nessun'altra parte in una funzione a scopo di documentazione. Perché l'uso eccessivo delle funzioni è migliore di un uso eccessivo dei commenti? L'utilizzo di funzioni del genere equivale a includere le istruzioni GOTO: crea codice spaghetti che può essere difficile da seguire.

Essenzialmente, quando lavori in un ambiente aziendale, in cui le persone condividono costantemente il codice e le persone non hanno sempre il tempo di perfezionare il codice, alcuni buoni commenti possono risparmiare un sacco di tempo e frustrazione. E ricorda, anche se potresti essere un guru che può leggere il codice alla velocità della luce, probabilmente non tutti nel tuo ufficio lo sono.

In tal caso, è facile fare una funzione descrittiva. Ma ho letto un sacco di codice fatto da bravi programmatori che credevano che il loro codice fosse auto-documentante, e quello che per loro era stato chiaro era davvero confuso per me.

$ extension = GetFileExtension ($ image_name);

Per tornare al tuo esempio, posso inviare una serie di nomi di immagini ad esso, o ci vuole solo una immagine? Supporta qualsiasi tipo di file o solo alcuni di essi? Mi proteggerà la stringa o devo farlo? Se il tipo di file non esiste, mi avvisa?

Naturalmente, sto allungando un po 'questo. Ma ricordo un programmatore che credeva che audio_bandwidth e video_bandwidth fossero dei nomi auto-documentanti; l'audio doveva essere espresso in byte e video in kilobyte. Ci è voluto un sacco di tempo per capirlo.

Uno non esclude l'altro. Anche se il tuo codice è auto-commentato, ci sono momenti in cui potresti aver bisogno di commenti regolari per spiegare perché il tuo codice auto-commentante fa quello che fa.

Non sono d'accordo con quell'articolo e sono d'accordo con te in una certa misura. Se usi nomi di metodi validi, nomi di variabili validi e metodi piccoli che fanno una sola cosa, il codice dovrebbe essere semplice da seguire.

Cerca di non essere furbo perché il codice intelligente è una lettura e una manutenzione orribile. Parola chiave: mantieni !

La mia opinione è che i commenti dovrebbero descrivere il perché e non il cosa. Ricorda in questo ipotetico mondo perfetto, il tuo codice è abbastanza pulito da consentire una facile lettura, non devi spiegare cosa sta facendo, ma perché hai scelto di farlo in questo modo o in quel modo.

Se utilizzi un sistema di controllo del codice sorgente, puoi utilizzare il messaggio di commit per consentire a tutti (ea te stesso) di sapere cosa hai fatto in un determinato momento e, soprattutto, perché. a

Bene, la cosa con il codice di auto-documentazione è che all'interno di quella funzione troverai:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

che è auto esplicativo quando si ha il nome della funzione dato che sono solo due righe. Quando le cose diventano più complicate, devi avvolgere ogni riga di codice in una funzione con un nome descrittivo o utilizzare i commenti se necessario .

Non ho mai capito perché dovrebbe essere un o / o materia, invece di e / e. Sì, rendi il tuo codice il più possibile auto-documentante possibile e, sì, aggiungi alcuni commenti alle parti che altrimenti sarebbero poco chiare.

Vorrai evitare di scrivere commenti proprio come vorresti evitare qualsiasi documentazione. Quando si tratta del linguaggio di programmazione, tutti operano con lo stesso insieme di vocaboli e sintassi (quasi).

Quando la tua app è per un determinato dominio, può essere difficile convincere tutti gli interessati a concordare e / o stabilire un vocabolario comune. Ci viene insegnato a evitare abbreviazioni e un ampio gergo, ma lo chiamerò

EBITDA

e non

EquityBeforeInterestTaxesDepreciationAndAmortization

Se non ne conosci uno, probabilmente non capisci l'altro. Se la compagnia ha qualche implementazione non comune, un commento potrebbe aiutare il prossimo programmatore che potrebbe avere esperienza nel dominio, ma non questa particolare azienda (il che rende solo le cose più complicate).

Penso che dobbiamo distinguere tra documentazione e espressività del codice.

Durante il debug o la revisione del codice, non stai leggendo un libro. La maggior parte delle volte si desidera passare da un metodo all'altro e creare rapide connessioni nella propria mente per ottenere una conoscenza di base di ciò che accade in fase di esecuzione. Non è la documentazione attorno al codice, ma l' espressività delle firme di codice che conta in quel processo, la loro capacità di essere abbastanza significative da poterle identificare immediatamente e aggiungerle a il proprio stack di chiamate interne. A quel punto, il nostro cervello (almeno, il mio funziona in questo modo;)) tende a considerare i grandi blocchi di commenti come un rumore piuttosto che come un aiuto. Pertanto, i commenti a una riga, o anche meglio, solo il metodo auto-descrittivo ei nomi degli oggetti sono sufficienti qui.

Se vuoi "leggere il libro" di una particolare classe o funzione, un posto molto migliore per questo è nei test unitari. I test unitari ben progettati sono per natura intenzionali-rivelatori e molto più documenti (cioè esplicativi, dettagliati) rispetto ai blocchi di commenti più spessi in quanto contengono 1 / le aspettative su esattamente cosa dovrebbe fare questo codice e 2 / la capacità di verificare queste aspettative rispetto al codice reale. Un test di passaggio è cento volte più affidabile di qualsiasi commento in termini di documentazione, perché dimostra che ciò che afferma è vero.

Alcuni codici non sono auto-documentati e richiedono alcuni commenti da un collega umano che ha capito e testato quel pezzo. Quello che ho qui sotto non è abbastanza per capirlo, credo.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

Generalmente preferisco scrivere codice di auto-documentazione, con commenti non chiari, poiché penso che la maggior parte del codice non si documenterà completamente da sola.

All'università ci è stato insegnato a riformulare praticamente ogni riga di codice in inglese con un commento (probabilmente solo per farci prendere l'abitudine di capire quale codice effettivamente fa, piuttosto che copiare / incollare qualcosa e sperare per il meglio) .

Personalmente, ritengo che il cluttering diavolo il codice, rendendolo less leggibile che se fosse solo commenti o solo codice. Sono un programmatore C # e gli unici commenti che faccio continuamente sono i blocchi di commento "tripla barra" interpretati alla documentazione di IntelliSense. Se mi sento particolarmente colpevole per un particolare modo di fare qualcosa, o se è particolarmente criptico, darò un'ulteriore spiegazione, ma questo è tutto.

IMO: il codice di auto-documentazione è il codice in cui i nomi di variabili e metodi ricevono nomi significativi e contestuali, in modo che descrivano qual è il loro scopo.

Se hai rivisitato il tuo codice più volte e ancora non hai trovato un modo per rendere chiara l'intenzione a qualcuno che conosce il dominio. Riscrivi la funzione. Dopotutto non ci sono più di 10-20 linee. Se è più lungo riscrivere la funzione comunque è troppo lunga e questo è parte del motivo per cui è illeggibile :) rinse-repeat

e nel caso improbabile non è ancora chiaro cosa stia facendo il codice e ti sei ricordato di chiedere aiuto ai tuoi colleghi. Bene, allora ti ringraziamo per aver aiutato l'evoluzione di Linux perché è il codice del kernel che stai scrivendo giusto? se non risciacquo-ripeti dall'alto:)

Semplicemente non scrivere non sei un commento, scrivili

Controlla codice Completa 2a edizione, pg 128-129.

Tipi di dati astratti ti salveranno da questo enigma. Il codice di auto-documentazione è la strada da percorrere. I commenti possono essere utili, ma avendo

real-world entities rather than low-level implementations

sei in grado di evitare l'uso di commenti.

Una cosa dei commenti è che li scrivi una sola volta, ma non li vedi quando implementi la funzione, li vedi solo quando cambi la funzione.

I commenti sono davvero utili quando sono interpretati dall'IDE come funzionano Delphi 2009+ o JavaDoc, ma si tratta più di un linguaggio di markup strutturato, quindi in un certo senso si sta programmando la documentazione, che è molto intelligente.

Credo nel mantra che il codice non si documenta da solo, perché potresti essere il miglior programmatore del mondo (Ada), eppure non capisci nulla di ciò che sta succedendo, ma se documenthi perché e in un po 'come il tuo codice sta facendo quello che fa, aiuterai te stesso e gli altri in futuro.

I commenti sono un must. Perché quando scrivi il codice, stai scrivendo per le tue esigenze attuali, ma anche per le persone che in futuro devono leggere il tuo codice, capire wtf, stai facendo, e perché, e poi come apportare modifiche per questo.

Se tenga questo a mente, quando codifica / programma?

Come posso semplificare la comprensione e la modifica per i futuri programmatori di questo codice su cui sto lavorando, quindi farai un buon lavoro. In caso contrario, stai solo rendendo difficile per gli altri modificare il tuo codice e non immaginare che non sarà mai così, è raro ...

Alla maggior parte del mio lavoro, ho dovuto sempre modificare il codice di altre persone e scritto in modo orribile, scarsamente documentato.

Quindi la tua abitudine di pensare che il codice documenta se stesso, non sta facendo la dovuta diligenza.

Come programmatori dobbiamo praticare l'autodisciplina che può sembrare totalmente a.r. ai programmatori inesperti, ma devono avere abitudini, per evitare tutte le esperienze orribili che abbiamo avuto con il codice di altre persone. O anche guardando il nostro codice mesi, anni dopo.

Dai un'occhiata al link che hanno tonnellate di storie divertenti ma reali sui programmatori che non hanno fatto la loro due diligence ..