Standard di codifica per chiarezza: commentare ogni riga di codice?

Ho lavorato in negozi che producono software critici per la vita e mi sono occupato delle regole di commento che avevano lo scopo di mantenere il codice leggibile e potenzialmente salvare vite. Nella mia esperienza, però, il requisito diventa un compito mortale per essere escluso da una lista di controllo e non mi aiuta a rimanere concentrato sulla scrittura di codice comprensibile. Inoltre distrae il mio revisore dei pari dall'avere una conversazione più significativa con me su come rendere il codice più facile da capire.

Ho anche valutato il codice dello studente che non aveva commenti e ho visto perché dovrebbero essere contrassegnati per averli trascurati.

Comprendo che l'uso di buoni nomi, la semplicità delle strutture, le funzioni brevi e i moduli focalizzati manterranno il codice sufficientemente comprensibile da ridurre al minimo i commenti.

Capisco anche che i commenti dovrebbero spiegare perché il codice fa quello che fa, non come.

Dato tutto ciò, è anche possibile scrivere buoni standard di codifica che catturano questa idea? Quelli che saranno rilevanti in una revisione tra pari, ma non si trasformeranno in un'attività di lista di controllo senza cervello che produce note non più utili di: "Hai dimenticato di commentare alla riga 42".

Un esempio del tipo di codice che questa regola potrebbe richiedere quando viene trattata come una riga in un elenco di controllo:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

Se è possibile esprimerlo correttamente in un documento standard, e potrebbe semplicemente non esserlo, mi piacerebbe catturare un'idea in questo modo:

Considera un commento per ogni riga, sequenza, istruzione, sezione, struttura, funzione, metodo, classe, pacchetto, componente, ... del codice. Quindi prendere in considerazione la ridenominazione e la semplificazione per eliminare qualsiasi necessità per quel commento in modo da poterlo eliminare. Fai il check-in mentre i commenti sono rari. Ripetere fino alla scadenza. Quindi ripeti ancora

La risposta di Michael Durrant è che IMHO non è male, ma non sta letteralmente rispondendo alla domanda (come ha ammesso da solo), quindi proverò a dare una risposta che:

Capisco anche che i commenti dovrebbero spiegare perché il codice fa quello che fa, non come.

Dato tutto ciò, è anche possibile scrivere buoni standard di codifica che catturano questa idea?

Ovviamente puoi scrivere una lista di controllo per le tue recensioni di codice , contenente domande come

• "se c'è un commento, spiega perché il codice fa quello che fa?"
• "ogni riga del codice - nel suo contesto - è sufficientemente autoesplicativa da non aver bisogno di un commento o, in caso contrario, è accompagnata da un commento che colma tale gap? O (preferibilmente) il codice può essere modificato in modo tale non ha più bisogno di un commento? "

Se lo desideri, puoi chiamarlo "standard di codifica" (oppure no, se ritieni che il termine standard di codifica debba essere riservato per un elenco di regole Braindead, a cui è facile rispondere se sono soddisfatte o meno, come la formattazione del codice dovrebbe apparire o dove dichiarare le variabili). Nessuno ti impedisce di focalizzare la tua lista di controllo su domande semantiche , invece di percorrere la strada facile e inserirvi solo regole formali .

Alla fine della giornata, dovresti essere sicuro che il tuo team abbia bisogno di una tale lista di controllo. Per applicare tali domande hai bisogno di programmatori con una certa esperienza come revisori e devi scoprire se migliorerà davvero la leggibilità del codice in un team di esperti. Ma è qualcosa che devi allenarti insieme al tuo team.

Importante anti-pattern che porta a un codice di scarsa qualità con meno chiarezza

tra i lettori, il titolo era originariamente "commentare ogni riga di codice?" e puoi immaginare la reazione istintiva di molti di noi, me compreso. In seguito sono tornato al titolo più lungo e preciso.

All'inizio, leggendo la tua domanda, ho pensato, roba duplicata nei commenti, ma ok, forse se hai abbastanza restrizioni sulle recensioni di più persone ... ma poi di nuovo: le persone commettono errori, non riescono a notare incoerenze, ecc. E nel tempo ci saranno differenze. Sulla riflessione, penso che il problema sia molto più grande:

Gli sviluppatori tenderanno a scrivere codice peggiore. Useranno nomi e strutture più criptici perché "è spiegato nel commento - vedi!".

Tener conto di:

living_room_set = tables + chairs.

Ora considera:

set = tbls+chrs # Make the set equal to the table plus the chairs

Non hai solo più nomi criptici e altro da leggere, devi anche guardare avanti e indietro, guardare il codice, che cos'è un set? guarda il codice a sinistra, guarda i commenti a destra, cosa sono tbls, guarda il codice a sinistra, guarda i commenti a destra, cosa sono i chrs, guarda i commenti a destra. Yuch!

Sommario

Sviluppa o migliora uno standard di commento se sei costretto a ricoprire la tua attuale posizione di sviluppatore (come ex programmatore COBOL ne ho sicuramente visti di grandi!) Ma hai speso tutto il tuo tempo, energia e passione a discutere contro l'anti- modello usando gli argomenti:

• Codice e commenti si sincronizzano tra loro quando ne viene modificato solo uno

• I commenti possono descrivere ciò che una persona pensa ma può essere sbagliato e quindi nascondere i bug

• Il codice diventa più difficile da leggere

• Un buon codice diventa più difficile da scrivere

• Tendenza ad aver usato nomi più criptici

• Caratteri eccessivi da leggere in codice e commenti

• Editor diversi usano stili diversi

• Richiede una conoscenza della lingua inglese superiore alla semplice codifica

• Prende tempo, risorse e sottrae dal valore a lungo termine *

Inoltre sostengono un codice migliore senza tali commenti, - in effetti hanno uno standard (!) - tutti i nomi delle variabili devono essere full_english_words - ce n'è uno! Quindi usa quell'energia "standard" verso gli standard di codice e test ben scritti.

Uno dei due problemi principali è la denominazione delle cose: non saltare il problema con i commenti.

Dato che uno degli altri problemi è l'ottimizzazione prematura e che l'ottimizzazione in generale può portare a oscurare il codice "perché in questo modo", questa è un'area in cui i commenti esplicativi per un codice apparentemente scarso possono essere utili anche se si applicano ancora le avvertenze di cui sopra.

* codice di domani

Non credo che un documento sugli standard di codifica sia il posto giusto per specificare ciò che è già buon senso. Lo scopo di uno standard di codifica è garantire coerenza (ed evitare argomenti) su questioni in cui le persone ragionevoli potrebbero non essere d'accordo e non esiste una sola risposta giusta ovvia, ad esempio convenzioni di denominazione, rientro ecc.

I commenti come nel tuo esempio sono oggettivamente inutili e potrebbero essere dovuti a uno sviluppatore inesperto, o uno sviluppatore che lavorava con un sistema di build che controlla meccanicamente la presenza di commenti (una pessima idea, ma esiste). In entrambi i casi la soluzione è l'educazione, possibilmente attraverso revisioni del codice.

Se inizi ad aggiungere tutti i tipi di "migliori pratiche" allo standard di codifica, finirai per ripetere ciò che è già indicato in più libri. Basta acquistare "Clean Code", "Code Complete" e "The Pragmatic Programmer" per lo sviluppatore in questione e mantenere snello lo standard di codifica.

Non è possibile. Ciò che stai essenzialmente cercando di fare è quasi meccanizzare il buon senso.

Quando si scrivono software critici come i sistemi medici a supporto della vita, enormi quantità di liste di controllo e quant'altro sono praticamente inevitabili. Non solo le persone intelligenti commettono errori, molto del software per questi dispositivi è scritto da persone che non sono molto brave nel loro lavoro, quindi il "sistema" deve essere in grado di salvaguardare dal lavoro sciatto, rendendolo sicuro a le spese di commerciabilità.

La tua migliore opzione è quella di tralasciare il rigoroso standard di codifica per commentare e guidare il team con l'esempio. Mostra agli altri quali sono i buoni commenti cercando di produrre un codice di buona qualità che sia opportunamente commentato. Invece di cercare di trovare il modo migliore per descrivere come scrivere commenti (che sono essi stessi più spesso che non una chiamata di giudizio) mostra agli altri cosa intendi quotidianamente con le tue recensioni di codice. Mentre gli altri membri leggono il tuo codice, seguiranno l'esempio se lo riterranno utile. E se non ci riescono, allora nessuno Standard li aiuterebbe a scrivere commenti migliori per cominciare.

Aggiornare

La mia risposta tra virgolette per enfasi:

Sono convinto che la risposta che afferma che i commenti non dovrebbero essere affrontati negli standard di codifica e che quindi elenchi una serie di domande difensive per combatterla, è l'unica risposta corretta.

Il problema qui è che uno standard di codifica è proprio questo, uno standard . Le idee estremamente soggettive non dovrebbero rientrare in uno standard di codifica . Può essere presente in una guida alle best practice, ma tale guida non può essere utilizzata contro uno sviluppatore durante la revisione del codice. A mio avviso personale, uno standard di codifica dovrebbe essere il più vicino possibile al più automatizzato. C'è così tanto tempo sprecato in Code Reviews a discutere di nomi, spaziature, tabulazioni, parentesi, commenti, ecc. Ecc. Quando TUTTO può essere automatizzato. Anche la risposta su tablese chairspuò essere automatizzata. LINT'er consente dizionari, controlli di capitalizzazione per concetto (variabile, funzione, metodo, classe, ecc.).

Anche il controllo JavaDoc può essere implementato da un robot LINT'er prima che una richiesta pull sia accettata. Molti progetti Open Source fanno esattamente questa cosa. Invia la tua richiesta pull, il codice viene creato con un file Travis-CI, inclusa l'analisi statica, e deve superare tutti gli standard di codifica che possono essere espressi in modo obiettivo. Nessun essere umano parla di "farlo in modo errato" o di non "fornire valore" con un commento o il modo sbagliato di nominare le variabili, ecc. Quelle discussioni non danno alcun valore e sono meglio lasciare a un robot di terze parti che può prendere il peso della nostra codifica emotiva.

Per rispondere effettivamente alla domanda dovremmo rivolgerci a come scrivere uno standard che si rivolge a come rispondere alla seguente domanda: questo commento ha fornito valore? Uno standard di codifica non può dettare il "valore" di un commento. Perciò diventa necessario che un essere umano passi attraverso quella lista di controllo. La semplice menzione di commenti in uno standard di codifica crea una lista di controllo che il poster originale vuole evitare.

Ecco perché i commenti di solito non vengono elaborati dal compilatore e rimossi. Il loro valore non può essere determinato. Il commento in questione è prezioso; si o no?. Rispondere a questa domanda è NP-difficile. Solo gli umani hanno la possibilità di rispondere correttamente, e anche allora può essere data risposta solo nel momento in cui viene letto, dalla persona che lo sta leggendo; dove il valore di quel commento è influenzato dal tempo, dalla sua vita domestica, dall'ultimo incontro a cui hanno appena partecipato e che non si è concluso bene, dall'ora del giorno, dalla quantità di caffè che hanno avuto. Confido che l'immagine stia diventando più chiara.

Come può mai essere espresso correttamente in qualsiasi standard? Uno standard non è utile a meno che non possa essere applicato in modo coerente ed equo, laddove la correttezza riguarda più l'oggettività non emotiva.

Contesto che uno standard di codifica debba rimanere il più obiettivo possibile. Il modo in cui le variabili sono denominate obiettivo IS. Possono essere facilmente verificati in un dizionario per la corretta ortografia, struttura grammaticale e involucro. Qualunque cosa oltre a ciò è una "partita pissing" che viene vinta dalla persona con più potere o "battendo le sopracciglia". Qualcosa che, personalmente, faccio fatica a NON fare.

Quando commento, commento sempre parlando con il mio io futuro in terza persona. Se torno a questo codice tra 5 anni, cosa dovrei sapere? Cosa sarebbe utile, cosa sarebbe confuso e cosa non sarebbe aggiornato con il codice? Esiste una differenza tra il codice di documentazione per generare un'API pubblica ricercabile e il codice di commento che fornisce valore a una terza parte sconosciuta, anche se quella terza parte è te stesso.

Ecco una buona cartina di tornasole. Se tu fossi l'UNICO sul progetto. Sapevi che saresti stato l'unico sul progetto. Quale sarebbe il tuo standard di codifica? Vorresti che il tuo codice fosse pulito, autoesplicativo e comprensibile a te stesso in futuro. Avresti una revisione del codice con te stesso sul perché non hai inserito un commento su ogni riga? Revisioneresti ogni singolo commento che hai creato sui 100 file che hai registrato? Se no, allora perché forzare gli altri?

Qualcosa che credo manchi in queste discussioni è che Future You è anche uno sviluppatore di questo progetto. Quando chiedi del valore, domani sei anche una persona che può derivare valore dal commento. Quindi la dimensione della squadra, secondo me non ha importanza. L'esperienza di squadra non ha importanza, cambia troppo spesso.

Nessuna quantità di codice di commento che esamina questo impedisce a un pacemaker di schiantarsi e uccidere un paziente. Quando parli di un commento che influisce sul codice, ora stai parlando del codice e non del commento. Se tutto ciò che serve è un commento mancante per uccidere qualcuno, c'è qualcos'altro che puzza nel processo.

La soluzione a questo tipo di rigoroso metodo di codifica è già stata fornita come metodologia per la scrittura del software stesso. E non ha nulla a che fare con i commenti. Il problema con i commenti è che NON hanno alcun impatto sul modo in cui funziona il prodotto. I migliori commenti al mondo non possono impedire il crash del software se incorporato in un pacemaker. O quando si misurano i segnali elettrici con un elettrocardiogramma portatile.

Abbiamo due tipi di commenti:

Commenti leggibili dalla macchina

Stili di commento come Javadoc, JSDoc, Doxygen, ecc. Sono tutti modi per commentare l'interfaccia pubblica fornita da un set di codice. Tale interfaccia può essere utilizzata solo da un altro sviluppatore (codice proprietario per un team di due persone), un numero sconosciuto di sviluppatori (ad esempio JMS) o per un intero reparto. Questo codice può essere letto da un processo automatizzato che produce quindi un modo diverso di leggere quei commenti, ala HTML, PDF e simili.

Questo tipo di commento è facile da creare uno standard per. Diventa un processo oggettivo per garantire che ogni metodo, funzione, classe invocabile pubblicamente contenga i commenti richiesti. Intestazioni, parametri, descrizione et. EL. Questo per garantire che sia facile per un altro team trovare e utilizzare il codice.

Sto facendo qualcosa che sembra pazzo, ma in realtà non lo è

Questi commenti sono qui per aiutare gli altri a capire PERCHÉ questo codice è stato scritto in un certo modo. Forse c'è un errore numerico nei processori su cui il codice è in esecuzione e viene sempre arrotondato, ma gli sviluppatori in genere gestiscono il codice che arrotonda. Quindi, commentiamo per garantire che uno sviluppatore che tocchi il codice capisca perché il contesto attuale stia facendo qualcosa sembrerebbe normalmente irragionevole, ma in realtà è stato scritto apposta in questo modo.

Questo tipo di codice è ciò che causa così tanti problemi. In genere diventa non commentato e successivamente viene trovato da un nuovo sviluppatore e "risolto". Rompendo così tutto. Anche allora, i commenti sono lì solo per spiegare il PERCHE 'per non impedire effettivamente che qualcosa si rompa.

Non è possibile fare affidamento sui commenti

I commenti sono in definitiva inutili e non ci si può fidare. I commenti normalmente non cambiano il modo in cui i programmi vengono eseguiti. E se lo fanno, allora il tuo processo sta causando più problemi, quindi dovrebbe. I commenti sono ripensamenti e non possono essere altro che. Il codice è tutto ciò che conta in quanto è tutto ciò che viene elaborato dal computer.

Questo può sembrare stupido, ma abbi pazienza. Quale di queste due linee conta davvero?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

In questo esempio, tutto ciò che conta è che non abbiamo idea di cosa sia 'n', non c'è alcun controllo per n essendo 0 E anche se non ci fosse, nulla impedisce a uno sviluppatore di mettere n = 0DOPO il controllo per 0. Quindi, il commento è inutile e nulla di automatizzato potrà mai capirlo. Nessuno standard può capirlo. Il commento, sebbene carino (per alcuni) non influisce sul risultato del prodotto.

Test Driven Development

Che cosa ha un esito sul prodotto? Le industrie in cui il codice in fase di scrittura possono letteralmente salvare o uccidere qualcuno devono essere rigorosamente controllate. Questo viene fatto attraverso revisioni del codice, revisioni del codice, test, test, revisioni del codice, test unitari, test di integrazione, prove, stadiazione, mesi di test, revisioni del codice e prove individuali, stadiazione, revisioni del codice, test e poi forse finalmente andare in produzione. I commenti non hanno nulla a che fare con questo.

Preferirei un codice che NON avesse commenti, una specifica, prove unitarie che verificassero le specifiche, studi sui risultati dell'esecuzione del codice sul dispositivo di produzione, quindi codice ben documentato che non era mai stato testato, né che avesse nulla per confrontare il codice contro.

La documentazione è buona quando stai cercando di capire PERCHÉ qualcuno ha fatto qualcosa in un certo modo, tuttavia, negli anni ho scoperto che la documentazione viene in genere utilizzata per spiegare perché è stato fatto qualcosa di "intelligente", quando in realtà non è stato necessario essere scritto in quel modo.

Conclusione

Se lavori in un'azienda che RICHIEDE che ogni riga sia commentata, GARANTISCO che almeno due ingegneri del software sul progetto hanno già scritto un programma di auto-documento in Perl, Lisp o Python che determina l'idea generale di ciò che la linea sta facendo , quindi aggiunge un commento sopra quella riga. Poiché ciò è possibile, significa che i commenti sono inutili. Trova gli ingegneri che hanno scritto questi script per documentare automaticamente il codice e usali come prova del perché il "Comment on Every Line" sta sprecando tempo, non fornendo alcun valore e potenzialmente danneggiando.

A parte, stavo aiutando un caro amico con un incarico di programmazione. Il suo insegnante aveva stabilito che ogni riga doveva essere documentata. Quindi posso vedere da dove verrebbe questo processo di pensiero. Chiediti semplicemente, cosa stai cercando di fare ed è questa la cosa giusta? Quindi chiediti; Esiste un modo per "giocare" al sistema con questo processo? Se c'è, allora sta davvero aggiungendo qualche valore? Non si possono scrivere automaticamente unit test che testano quel codice soddisfa una determinata specifica e, se possibile, non sarebbe una brutta cosa.

Se un dispositivo deve funzionare in determinate condizioni perché si troverà all'interno di un essere umano, l'unico modo per assicurarsi che non li uccida è anni di test, peer review, prove e quindi MAI MAI PIÙ cambiare di nuovo il codice. Questo è il motivo per cui la NASA utilizza / utilizzava ancora hardware e software così vecchi. Quando si tratta di vita o morte, non basta "apportare un piccolo cambiamento e controllarlo".

I commenti non hanno nulla a che fare con il salvataggio di vite. I commenti sono per gli umani, gli umani commettono errori, anche quando scrivono commenti. Non fidarti degli umani. Ergo, non fidarti dei commenti. I commenti non sono la tua soluzione.

Ci sono due cose diverse a cui alludi quando parli di commenti. Non sono gli stessi e la distinzione è importante.

La documentazione descrive i bit rivolti verso l'esterno di un pezzo di codice: la sua interfaccia.

Tipicamente gli strumenti ti permetteranno di leggerli in modo "autonomo", cioè non stai guardando il codice sottostante allo stesso tempo.

Tutta l'interfaccia dovrebbe essere documentata (ad esempio ogni metodo, esclusi i metodi privati) e dovrebbe descrivere input, output e qualsiasi altra aspettativa, limitazione, ecc., In particolare cose che non possono essere espresse attraverso vincoli, test, ecc. ( Quanti dettagli e dove vanno dipendono dal progetto).

Una buona documentazione consente al potenziale consumatore di decidere se, quando e come utilizzare il codice.

I commenti nel codice sorgente hanno uno scopo diverso. Sono lì per le persone che guardano il codice sorgente. Descrivono principalmente l'implementazione.

I commenti vengono sempre letti nel codice sottostante.

I commenti dovrebbero spiegare decisioni sorprendenti o algoritmi complessi o opzioni non prese (e ragionamento). Sono lì così i futuri sviluppatori possono capire i processi di pensiero dei loro predecessori e avere a portata di mano informazioni che altrimenti potrebbero trascurare o impiegare molto tempo a cercare, ad es.

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

Non puoi dedurre nulla dall'assenza di un commento, e il commento può ovviamente essere sbagliato quanto il codice circostante o più. Il giudizio deve essere esercitato sia da parte dell'autore che da parte del lettore.

Commentare ogni riga è chiaramente più lavoro di discutibile valore aggiunto, che comporta un costo opportunità. Se hai una regola che dice che ogni riga deve essere commentata, la otterrai, ma a spese di parti importanti che vengono commentate bene .

Ma è peggio di così: lo scopo di un commento viene sconfitto se ogni riga viene commentata. I commenti diventano rumori che rendono il codice difficile da leggere: oscurare piuttosto che chiarire. Inoltre, i commenti indiscriminati rendono più difficili da individuare i commenti veramente importanti.

Né i commenti né la documentazione forniscono alcun tipo di misura o garanzia della qualità del codice che descrivono; non sostituiscono il QA originale. Il loro scopo è lungimirante, cioè nella speranza che possano aiutare coloro che interagiscono con esso ad evitare errori.

In sintesi , i tuoi standard di codifica possono e dovrebbero richiedere documentazione (i controlli automatici aiutano a individuare funzioni / metodi non documentati, ma gli umani devono ancora verificare se la documentazione è valida). I commenti sono un appello di giudizio e la tua guida di stile dovrebbe riconoscerlo. Chi non commenta mai e chi commenta senza pensare dovrebbe aspettarsi di essere sfidato.

Non puoi codificare uno standard di commento, perché non puoi sapere quale sarà il commento importante in anticipo.

Ma vuoi ancora assicurarti che il codice sia commentato correttamente, poiché questo è un codice critico per la vita. La soluzione è quella di avere uno standard per la revisione del codice - richiede che i commenti di revisione del codice sulla comprensibilità.

Ciò non garantisce che non si trasformerà in un elenco di controllo privo di significato, ma almeno gli impedirà di rendere il codice più difficile da leggere. E ha la possibilità di renderlo migliore.

Ciò richiede una cultura in cui una revisione del codice non è di per sé un gesto insignificante, in cui ottenere il codice inviato come difficile da leggere è una buona cosa, e non un insulto o un fastidio. Altrettanto importante, uno in cui dire che non era chiaro, non è visto come un fallimento del lettore.

Il codice illeggibile è, in una certa misura, inevitabile. Perché lo scrittore è immerso nel contesto e vedrà qualcosa di ovvio quando è ovvio solo se conosci x, y o z.

Quindi, non sarai in grado di avere una regola che dice dare un buon feedback, ma puoi controllare le recensioni. Anche un manager non programmatore potrebbe farlo - perché la vera domanda non è il codice scritto per essere leggibile, ma era il codice effettivamente leggibile, che può essere deciso solo da qualcuno che lo legge.

Commenta ogni riga di codice? No .

Lo scopo delle altre regole di cui parli è proprio quello di evitarlo.

I commenti a un codice leggibile sono nella migliore delle ipotesi ridondanti e, nella peggiore delle ipotesi, scoraggiano un lettore a cercare lo scopo inesistente del commento.

Se commentate l'intero codice che si spiega da sé, raddoppiate la quantità di letture senza fornire ulteriori informazioni. Non sono sicuro se tale ridondanza sarebbe ripagata. Si può immaginare un critico dicendo che 42 dice "display_error " mentre il commento dice "visualizza avvertimento". Ma immagina un cambiamento nel codice. Hai due posti per correggere ora. Diventa chiaro che questo stile ha negativi copia-incolla.

Direi che in modo ottimale il codice non dovrebbe avere bisogno di commenti, oltre alla documentazione.

Ci sono stili che vanno completamente al contrario, se hai dei dubbi sulla linea è:

1. Il codice è troppo complicato e dovrebbe essere modificato in una funzione con un nome con un significato semantico per la parte di codice. Sia esso un complesso ifo una porzione di un algoritmo. (O un intelligente LINQ one-liner)

2. Se non può essere semplificato, non conosci abbastanza idiomi del linguaggio.

(Personalmente non sono un fanatico della rigorosa regola dei non commenti, ma trovo che sia una buona mentalità iniziale da seguire.)

Dato tutto ciò, è anche possibile scrivere buoni standard di codifica che catturano questa idea?

Per quanto riguarda il processo. Il nostro standard ha dato molto credito al revisore. Supponendo che non siano malevoli, questo funziona bene.

Quando chiede "Cos'è la variabile o ?", La rinominate. Se chiede cosa fa questo blocco, sia refactor che commento. Se c'è stato un dibattito sul fatto che qualcosa sia chiaro o no, se il recensore non l'ha capito, per definizione non lo è. In occasioni molto rare c'era qualcosa come la seconda opinione di pochi amici.

In media, dovresti ottenere un codice comprensibile dal programmatore medio nel team. IMO mantiene lontane le informazioni ridondanti e garantisce che il codice sia comprensibile da almeno un altro membro del team, che abbiamo trovato un ottimo ottimale.

Inoltre, non c'erano assoluti . Anche se eravamo un piccolo gruppo. È facile trovare consenso nel gruppo di 5.

La domanda:

Dato tutto ciò, è anche possibile scrivere buoni standard di codifica che catturano questa idea? Quelli che saranno rilevanti in una revisione tra pari, ma non si trasformeranno in un'attività di checklist insensata che produce note non più utili di: "Hai dimenticato di commentare sulla riga 42".

I commenti non devono cercare di educare il lettore alla lingua. Si presume che un lettore conosca la lingua meglio dello scrittore, ma con un contesto molto meno rispetto allo scrittore.

Un lettore di questo codice, dal tuo esempio, dovrebbe sapere che exit()uscirà dall'applicazione, rendendo così superfluo il commento:

/* Exit the application */
exit();

I commenti ridondanti sono una violazione di DRY e le modifiche al codice non si propagano necessariamente ai commenti, lasciando commenti che non riflettono ciò che il codice sta effettivamente facendo.

Tuttavia, i commenti che spiegano perché stai facendo qualcosa possono essere preziosi, soprattutto se non riesci a comunicare facilmente il significato nel codice stesso.

PEP 8 di Python (la guida di stile per Python nella libreria standard di CPython) fornisce le seguenti linee guida per i commenti incorporati:

Usa i commenti in linea con parsimonia.

Un commento in linea è un commento sulla stessa riga di un'istruzione. I commenti incorporati devono essere separati da almeno due spazi dall'istruzione. Dovrebbero iniziare con un # e un singolo spazio.

I commenti in linea non sono necessari e, in effetti, sono fonte di distrazione se affermano l'ovvio. Non farlo:

x = x + 1                 # Increment x

Ma a volte, questo è utile:

x = x + 1                 # Compensate for border

Dato un esempio del genere, personalmente preferisco fare un ulteriore passo avanti e proverei a eliminare anche questo commento. Ad esempio, potrei arrivare a:

border_compensation = 1
compensated_x = x + border_compensation

Rendere l' auto-documentazione del codice non è una nuova idea .

Torna alla domanda reale:

Dato tutto ciò, è anche possibile scrivere buoni standard di codifica che catturano questa idea?

Credo che la guida e l'esempio PEP 8 dimostrino un buon standard di codifica che cattura questa idea. Quindi sì, credo che sia possibile.

Penso che quando vedi questo tipo di commenti, e scrivo in questo modo di tanto in tanto io stesso, è perché l'autore sta scrivendo la specifica nei commenti e poi sta esaminando e implementando ogni commento.

Se siamo sfidati a scrivere uno standard di codifica che produca un codice comprensibile in termini di funzionalità richiesta anziché di funzionalità effettiva (in modo che gli errori possano essere individuati), stiamo davvero parlando di come vengono definite, documentate e collegate le specifiche il prodotto finale?

modificare ----

Tanto per chiarire. Non sto entrando nei commenti vs tdd vs unit test quale meglio. O suggerire un commento per riga è un buono / cattivo

Sto solo suggerendo un motivo per cui potresti vedere lo stile dei commenti di cui abbiamo parlato nell'esempio.

E da quella domanda se uno standard di codifica sui commenti sarebbe effettivamente meglio scritto come un requisito di documento di specifica di qualche tipo.

vale a dire i commenti servono a spiegare lo scopo del codice, che è anche ciò che è una specifica

Dato tutto ciò, è anche possibile scrivere buoni standard di codifica che catturano questa idea? Quelli che saranno rilevanti in una revisione tra pari, ma non si trasformeranno in un'attività di checklist insensata che produce note non più utili di: "Hai dimenticato di commentare sulla riga 42".

Questo ovviamente va al di là della documentazione: tocca il modo in cui è strutturato il codice, quali algoritmi sono stati scelti, ecc. Può persino toccare l'analisi e la progettazione dei requisiti.

La mia regola n. 1 è "Non documentare l'ovvio". La regola n. 2 è "Scrivi codice ovvio".

Per il codice critico per la sicurezza (su cui non ho mai dovuto lavorare, grazie a Dio), questo è un primo passo necessario ma quasi impossibile. Potrebbe anche essere necessario ridurre le caratteristiche del linguaggio da evitare (ho visto più di un mandato standard "Non devi usare scanf( "%s", input ); per nessun motivo ").

La migliore pratica del codice autocompensante non è un consenso mainstream - mentre è ampiamente accettabile che il codice di facile comprensione sia migliore del codice criptico, non tutti sono d'accordo sul fatto che il codice complicato debba sempre essere riformulato o se è OK per commentare esso.

Ma questo dibattito riguarda pezzi di codice che sono difficili da capire - e stai parlando di commentare ogni singola riga di codice. Le righe di codice che sono difficili da capire dovrebbero essere molto rare - se la maggior parte delle tue linee sono complicate in questo modo, allora stai abusando di una riga di linea intelligente e dovresti smettere! Certo, il ruolo di una linea può essere un po 'difficile da capire a volte, ma è il ruolo nel contesto di un pezzo di codice più grande - quello che fa la linea stessa è quasi sempre semplice.

Quindi, non dovresti commentare le righe - dovresti commentare pezzi di codice. Commenti specifici possono essere posizionati vicino alle righe a cui fanno riferimento, ma questi commenti si riferiscono ancora al codice più grande. Non descrivono cosa / perché la linea lo fa - descrivono cosa fa in quel codice e / o perché è necessario in quel codice.

Quindi, non sono le righe che dovrebbero essere commentate, ma pezzi di codice più grandi. Ogni parte di codice dovrebbe essere commentata? No. Harold Abelson ha affermato che "i programmi devono essere scritti per essere letti dalle persone, e solo per inciso per l'esecuzione delle macchine ". Ma i commenti sono solo per le persone a leggere - la macchina non li esegue. Se i tuoi standard di codifica impongono la scrittura di commenti ridondanti su ogni riga / pezzo di codice, non stai solo caricando lo sviluppatore che deve scriverli, ma stai anche gravando sugli sviluppatori che dovranno leggerli !

Questo è un problema, perché quando la maggior parte dei commenti che leggi sono ridondanti, smetti di prestar loro attenzione (perché sai che saranno solo spazzatura ridondante), e poi perderai i commenti importanti . Quindi dico: scrivi solo il commento importante, in modo che quando qualcuno vede un commento nel codice sappia che vale la pena leggerlo per capire il codice.

IMHO dovrebbe fare entrambe le cose. Commentare ogni riga è sciocco, perché finisci con righe simili

  i++;    /* Increment i */

senza alcun indizio sul motivo per cui vorresti incrementare i. Espandilo un po 'e hai il tipico stile Doxygen di commenti, che producono una grande quantità di verbosità senza fornire alcuna idea di cosa sia il codice o di come funzioni. (Almeno per quanto ho mai visto: ammetto che potrebbe essere possibile scrivere una documentazione utile usando un sistema del genere, ma non trattengo il respiro.)

OTOH, se scrivi un buon blocco di commenti a capo della funzione (o qualunque raggruppamento sia logico), descrivendo sia ciò che deve essere realizzato, sia come, se è meno che ovvio, hai qualcosa di utile. Se sei me, potresti anche includere il codice LaTeX per le equazioni pertinenti, o riferimenti a documenti, ad esempio "Questo implementa uno schema WENO per risolvere le equazioni di Hamilton-Jacobi, come discusso in ..."

È tempo di riportare i diagrammi di flusso! (non proprio, ma aspetta un minuto)

L'altro giorno ho trovato il mio vecchio modello di diagramma di flusso. L'ho usato solo per i compiti e le battute (devi amare un buon diagramma di flusso sciocco). Ma anche a questo punto la maggior parte dei programmatori commerciali che utilizzavano ancora diagrammi di flusso li generava automaticamente dal codice (il che mina completamente lo scopo originale del diagramma di flusso, che doveva essere un aiuto nella scrittura di codice migliore ed era abbastanza utile nel codice macchina. Tuttavia, con linguaggi di livello superiore, il diagramma di flusso è passato da stampella a cavalletto. Perché l'astrazione del diagramma di flusso era la stessa del codice. I commenti mostrati sono un ostacolo in quanto si trovano allo stesso livello di astrazione del codice. I buoni commenti hanno un diverso livello di astrazione rispetto al codice: il modo più semplice per farlo è usare i commenti per quale motivo mentre il codice gestisce cosa.

Risponderò alla domanda come indicato:

Dato tutto ciò, è anche possibile scrivere buoni standard di codifica che catturano questa idea?

Sì. WYSIWYG. Un buon standard di codifica è letteralmente " è chiaro al lettore cosa fa il seguente codice e perché ".

In altre parole, i miei commenti di revisione del codice sulla leggibilità del codice letteralmente, 1-1, derivano dal mio stato mentale di

Come lettore (meglio ancora, come standard minimo, un modello mentale di un lettore meno esperto ma ragionevole), non capirei lo scopo del codice seguente o il metodo di lavoro

In genere, le persone sono facili da ottenere "ciò richiede maggiore leggibilità" quando sentono "Io, come sviluppatore senior che speri tu stia rispettando come non stupido, all'inizio non ho capito questo codice o perché è lì o cosa sì, quindi deve essere spiegato ".

Questo sposta il discorso da "non hai seguito uno standard insignificante" a "il tuo codice ha una specifica carenza di leggibilità che porta a problemi pratici ".

Un secondo standard che deve essere reso esplicito è il "test di emergenza alle 2:00".

Il tuo backup, che non ha esperienza con questo codice, può capire qual è il problema con il codice quando esegui il debug durante la chiamata del bridge di emergenza di produzione alle 2 del mattino, quando sei in vacanza nelle Ande cilene senza telefono cellulare?

Questo può sembrare soggettivo ma in realtà è facile da misurare praticamente: chiama un membro del team junior casuale che dovrebbe essere il debug di notte in caso di emergenza di produzione e chiedi loro di spiegare come funziona il particolare codice non commentato e perché è Là.

Questa risposta ha riguardato la maggior parte dei problemi, tuttavia esiste una cosa importante.

Vorrei catturare un'idea sulla falsariga di: prendere in considerazione un commento per ogni riga, sequenza, istruzione, sezione, struttura, funzione, metodo, classe, pacchetto, componente, ... del codice.

Esistono strumenti per generare documentazione dal codice, come ad esempio doxygen. Se usi questi strumenti, allora ha senso commentare file, funzioni, classi, ecc. Anche se il nome della funzione è autoesplicativo, lo sto ancora facendo per coerenza, perché le persone che leggono la documentazione saranno grate.

Molte delle risposte esistenti sono ben dettagliate, ma ho ritenuto importante rispondere:

... [commenti] che saranno rilevanti in una revisione tra pari ma non si trasformeranno in un'attività di checklist insensata ...

Per me gli unici commenti che potrebbero essere uno standard possono essere risolti chiedendo quali commenti vengono notati quando mancano . In altre parole: commenti utilizzati da IDE o software di documentazione.

Detto questo, questo è soggettivo a quali strumenti vengono utilizzati dagli sviluppatori e non tutti i commenti utilizzati da tale software sono utili l'uno rispetto all'altro .