Ho effettuato una ricerca ma non ho trovato quello che cercavo, non esitare a collegarmi se questa domanda è già stata posta.

All'inizio di questo mese è stato pubblicato questo post:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

In sostanza, per riassumere, sei un cattivo programmatore se non scrivi commenti. La mia opinione personale è che il codice dovrebbe essere descrittivo e per lo più non richiedere commenti, a meno che il codice non possa essere auto-descrittivo.

Nell'esempio fornito

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

L'autore ha detto che questo codice dovrebbe ricevere un commento, la mia opinione personale è che il codice dovrebbe essere una chiamata di funzione che è descrittiva:

$extension = GetFileExtension($image_filename);

Tuttavia nei commenti qualcuno ha effettivamente dato proprio quel suggerimento:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

L'autore ha risposto dicendo che il commentatore era "una di quelle persone", cioè un cattivo programmatore.

Quali sono le opinioni altrui sul codice auto-descrittivo rispetto al codice di commento?

Preferisco scrivere codice auto-documentante. Una guida per questo è Clean Code .

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

Ovviamente, come ha notato @Niphra, vale sempre la pena di ricontrollare che ciò che credo sia pulito è davvero comprensibile da altri. Tuttavia, anche questa è una questione di pratica. Nell'università ho scritto pezzi di codice enigmatici semplicemente per l'uso di nomi strani e divertenti per tutte le entità di codice, secondo il mio capriccio. Fino a quando il mio insegnante ha annullato uno dei miei compiti, notando educatamente che non riusciva a capire quale modulo fosse il principale :-) Questa è stata una buona lezione, quindi ho cercato di concentrarmi sulla scrittura di codici sempre più leggibili da allora. Oggi difficilmente ricevo lamentele dai compagni di squadra.

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

Nessuna quantità di trucchi per la denominazione esporrà perché e perché, quindi devi aggiungere commenti per spiegare lo scopo dei vari bit di codice.

Tutti gli altri commenti possono essere tranquillamente eliminati.

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

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

Quindi, commenta il tuo codice. Ovviamente non tutte le righe (buon cielo, no), ma metti alcune righe di commento sopra una funzione / subroutine / modulo , o una parte particolarmente complicata e in breve descrivi cosa fa. Ti ringrazierai tra un anno o due.

Fortunatamente, entrambi i campi di 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, il modo in cui raggiungerli è un po 'diverso.

Argomenti sovrapposti

• Il codice dovrebbe essere leggibile.
• I commenti non dovrebbero dire esattamente la stessa cosa del codice, ma fornire ulteriori approfondimenti ove necessario.
• Tutti i nomi di variabili / funzioni dovrebbero essere presi in considerazione in modo da fornire una buona rappresentazione di ciò che sono / fanno.
• Il codice duplicato dovrebbe essere prevenuto.

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

Codice auto-descrittivo

• I commenti possono diventare obsoleti, quindi riduci al minimo il loro utilizzo, poiché i commenti sbagliati sono peggio di nessun commento.
• I commenti sono una duplicazione del codice. Tutto ciò che può essere scritto in codice, dovrebbe essere scritto in codice.

Più commenti

• I commenti sono più leggibili del codice. L'inglese semplice è meglio nel descrivere qualcosa.

• Il codice semplice causa spesso ambiguità che devono essere comunque commentate. Cercando di descriverlo nel codice, si ottengono nomi troppo lunghi. Inoltre, ti trovi costantemente di fronte a queste informazioni "extra" di cui hai bisogno solo la prima volta che le incontri.

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

Per dimostrare, nel libro Clean Code , il codice è suddiviso in numerosi metodi più piccoli che vengono chiamati solo una volta. I metodi vengono creati per il solo motivo di documentare il codice (e TDD più semplice). Ciò si traduce in Funzione Inferno . Il codice è meno leggibile di quanto non fosse in origine e durante il refactoring non è stato pensato di incapsulare il codice riutilizzabile.

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

"Mi dispiace ma tu sei quel ragazzo."

Mi chiedo perché non gli piaccia commentare: P

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

Cerca la programmazione alfabetica come uno stile estremo.

La risposta breve, migliore e corretta

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

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

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

La spiegazione per il backup

Le persone pensano 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ù veloceper dare un'occhiata al tuo codice e trovare quello che stai cercando. Quando torno più tardi al codice o leggo il codice di qualcun altro, certo, posso leggere e comprendere una sezione di codice ben scritto, ma non è più veloce e più facile leggere il commento in alto dicendo cosa fa quella sezione di codice e saltarlo del tutto se non è quello che sto cercando? Perché sedersi lì 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é usiamo nomi descrittivi per le funzioni - nessuno dice che non ho bisogno di usare un nome descrittivo per la mia funzione perché qualcuno può semplicemente guardare attraverso il mio codice scritto in modo pulito per vedere cosa fa.

Ad esempio, se sto guardando 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 cosa sta facendo la funzione e dove lo sta facendo?

Un altro anti-pattern è l'uso eccessivo di funzioni per commentare il tuo codice. Le funzioni ben nominate 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 è meglio di un uso eccessivo dei commenti? Usare funzioni come questa è come abbracciare le istruzioni GOTO: crea un codice spaghetti che può essere una seccatura da seguire.

In sostanza, quando lavori in un ambiente aziendale, in cui le persone condividono costantemente il codice e le persone non hanno sempre il tempo di rendere perfetto il loro codice, alcuni buoni commenti possono farti risparmiare un sacco di tempo e frustrazione. E ricorda, mentre potresti essere un guru in grado di leggere il codice alla velocità della luce, probabilmente non tutti nel tuo ufficio lo sono.

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

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 si spiega da solo quando si ha il nome della funzione poiché sono solo due righe. Quando le cose si complicano, devi racchiudere ogni poche righe di codice in una funzione con un nome descrittivo o usare i commenti dove necessario .

Non ho mai capito perché dovrebbe essere una o / o materia, invece di e / e. Sì, rendi il tuo codice quanto più autocompattante possibile, e sì, aggiungi alcuni commenti alle parti che altrimenti non sarebbero chiare.

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

In tal caso, è facile creare una funzione descrittiva. Ma ho letto un sacco di codice fatto da bravi programmatori che credevano che il loro codice fosse auto-documentante, e ciò che era stato cristallino per loro mi stava davvero confondendo.

$ extension = GetFileExtension ($ image_name);

Per tornare al tuo esempio, posso inviargli un array di nomi di immagini o ci vuole solo un'immagine? Supporta qualsiasi tipo di file o solo alcuni di essi? Proteggerà la stringa per me o devo farlo? Se il tipo di file non esiste, mi avvisa?

Certo, lo sto allungando un po '. Ma ricordo un programmatore che credeva che audio_bandwidth e video_bandwidth fossero nomi autocompensanti; si è scoperto che l'audio doveva essere espresso in byte e il video in kilobyte. Ci è voluto molto 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 di auto-commento 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 di piccole dimensioni che eseguono una sola operazione, il codice dovrebbe essere semplice da seguire.

Cerca solo di non essere intelligente perché il codice intelligente è orribile da leggere e mantenere. 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 è necessario spiegare cosa sta facendo, ma perché hai scelto di farlo in questo modo o in quel modo.

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

Vorresti evitare di scrivere commenti proprio come vorresti evitare qualsiasi documentazione. Quando si tratta del linguaggio di programmazione stesso, tutti operano dalla stessa serie di vocaboli e sintassi (quasi).

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

Il margine operativo lordo

e non

EquityBeforeInterestTaxesDepreciationAndAmortization

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

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

Durante il debug o la revisione del codice, non stai leggendo un libro. Il più delle volte vuoi solo saltare da un metodo all'altro e creare connessioni rapide nella tua mente per ottenere una comprensione di base di ciò che sta accadendo in fase di esecuzione. Non è la documentazione attorno al codice, ma l' espressività delle firme del codice che conta in quel processo, la loro capacità di essere abbastanza significative da poterle identificare immediatamente e aggiungerle al proprio stack di chiamate interno. A quel punto, il nostro cervello (almeno, il mio funziona in quel modo;)) tende a considerare i grandi blocchi di commenti come un rumore piuttosto che un aiuto. Pertanto, i commenti di una riga, o ancora meglio, solo metodi autodescrittivi e nomi di oggetti sono sufficienti qui.

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

Un po 'di codice non è auto-documentato e richiede un commento da parte di un collega umano che ha capito e testato quel pezzo. Quello che ho sotto non è abbastanza per capirlo, penso.

//
// 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;
}

In genere preferisco scrivere codice auto-documentante, con commenti dove non è chiaro, dal momento che penso che la maggior parte del codice non si documenterà completamente.

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 cosa fa effettivamente il codice, piuttosto che semplicemente copiare / incollare qualcosa e sperare per il meglio).

Personalmente, immagino che ingombra il tuo codice, rendendolo meno leggibile che se fosse solo commenti o solo codice. Sono un programmatore C # e gli unici commenti che faccio continuamente sono i blocchi di commenti "triple-slash" che vengono interpretati nella documentazione di IntelliSense. Se mi sento particolarmente in colpa per un modo particolare di fare qualcosa, o sembra particolarmente criptico, darò un'ulteriore spiegazione, ma questo è tutto.

IMO: il codice autocompattante è un codice in cui i nomi delle variabili e dei metodi vengono assegnati a nomi significativi e contestuali, in modo che descrivano qual è il loro scopo.

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

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 tutti per aver contribuito a far evolvere Linux perché è il codice del kernel che stai scrivendo, giusto? se non risciacquo, ripetere dall'alto :)

In poche parole, non scrivere i tuoi commenti CODICI

Guarda il codice completo 2a edizione, pag. 128-129.

I 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

entità del mondo reale piuttosto che implementazioni di basso livello

sei in grado di evitare di usare i commenti.

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

I commenti sono davvero utili quando vengono interpretati dall'IDE nel modo in cui Delphi 2009+ o JavaDoc funzionano, ma è più un linguaggio di markup strutturato, quindi in un certo senso stai programmando la tua documentazione, che è molto intelligente.

Credo nel mantra che il codice non documenti se stesso, perché potresti essere il miglior programmatore al mondo (Ada), eppure non capisci nulla di ciò che sta succedendo, ma se documenti perché e in breve 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 in futuro che devono leggere il tuo codice, capire wtf, cosa stai facendo, e perché, e poi come modificarlo.

Se ti ricordi questo, durante la programmazione / programmazione?

Come posso rendere questo più facile da capire e modificare 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 il caso, è raro ...

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

Quindi l'abitudine di pensare che il documento in codice sia autonomo, non sta semplicemente facendo la dovuta diligenza.

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

Dai un'occhiata a http://thedailywtf.com che hanno tonnellate di storie divertenti ma reali sui programmatori che non hanno fatto la loro dovuta diligenza.