Guida per principianti alla scrittura di commenti?

27

Esiste una guida definitiva alla scrittura di commenti in codice, rivolta agli sviluppatori in erba?

Idealmente, coprirebbe quando i commenti dovrebbero (e non dovrebbero) essere usati e quali commenti dovrebbero contenere.

Questa risposta :

Non commentare COSA stai facendo, ma PERCHÉ lo stai facendo.

Il WHAT è curato da un codice pulito, leggibile e semplice con una corretta scelta dei nomi delle variabili per supportarlo. I commenti mostrano al codice una struttura di livello superiore che non può essere (o è difficile) mostrare dal codice stesso.

si avvicina, ma è un po 'conciso per programmatori inesperti (un'espansione su questo con diversi esempi e casi d'angolo sarebbe eccellente, penso).

Aggiornamento : oltre alle risposte qui, penso che questa risposta a un'altra domanda sia estremamente rilevante.

language-agnostic comments

— Cameron
fonte

Penso che ci stiamo rapidamente spostando in un mondo in cui le persone non commentano più. In meglio di (più probabile) in peggio. Agile.

— MK01

1

@MK: In questo caso (tendo ad essere più d'accordo con questa risposta ) , sarebbe utile una guida che spieghi come non scrivere commenti e perché dovrebbero essere evitati. È un dato di fatto, più punti di vista diversi, meglio è.

— Cameron,

Penso che piccoli commenti per migliorare la velocità di lettura del codice siano molto utili e lo saranno sempre. Non compro completamente il ragionamento del "commento stantio", anche se sono stantii, avrebbero un valore storico. Lavoravo su una base di codice che occasionalmente aveva commenti dettagliati qua e là e non sono mai stato morso dal fatto che il commento era un problema obsoleto.

— MK01

vedi anche: "I commenti sono un odore di codice"

— moscerino

38

Dovresti essere consapevole della più grande debolezza dei commenti: diventano stantii. Cioè, quando il codice cambia, gli sviluppatori raramente aggiornano i commenti per rimanere sincronizzati con il codice. Ciò significa che non puoi mai fidarti di loro e finire per leggere il codice. Proprio per questo motivo, il codice dovrebbe essere auto-documentato. Dovresti scegliere la tua funzione e i nomi delle variabili in modo tale che il codice legga come prosa.

Quindi non documentare COSA sta facendo il codice. Il codice auto-documentante dovrebbe occuparsene. Documento PERCHÉ lo stai facendo. I WHY di solito sono legati alle regole di business o all'architettura e non cambieranno spesso e diventeranno stantii velocemente ai WHAT. Custodie per documenti. Eccezioni al documento. Decisioni di progettazione del documento. E, soprattutto, documenta le decisioni di progettazione che avevi preso in considerazione, ma che hai deciso di non implementare (e documenta PERCHÉ hai deciso di non usarle).

2

L'ultimo è molto importante. A volte c'è un bug / effetto collaterale con l'implementazione della soluzione ovvia. Documentare il motivo per cui hai scelto di utilizzare un'altra soluzione impedisce allo sviluppatore successivo di reintrodurre il bug quando "risolvono" la tua soluzione apparentemente scadente.

— CaffGeek,

2

Un altro punto, il mio primo lavoro ha considerato i commenti importanti quanto il codice. Cerca di prendere l'abitudine di leggere i commenti e il codice quando esegui il peer review e cerca di insistere sul fatto che i commenti siano aggiornati quando possibile. Ciò consente di evitare che i commenti diventino obsoleti e mantiene aggiornate le regole aziendali, ecc. Documentate nel codice.

— Eric Hydrick,

10

Dovresti leggere il libro Clean Code di Robert C. Martin . Spiega bene che se hai bisogno di commenti, molto probabilmente non stai codificando correttamente. Idealmente, il tuo codice dovrebbe essere "auto-commento". Il libro Clean Coder spiega come fare ciò, in modo che i commenti non siano necessari, e descrive bene come fare commenti in situazioni in cui è necessario. (Come spiegare una complessa formula matematica)

— peso
fonte

Anche se non vorrei tanto una complessa formula matematica spiegata come vorrei che fosse scritta in una corretta notazione matematica (possibilmente TeX), con una spiegazione del suo significato e della sua fonte. Se non capisci la formula, non dovresti fare confusione con il codice che la utilizza per calcolare comunque un valore, dal momento che è eccezionalmente probabile rovinare e introdurre bug (sottili o no).

— un CVn del

Il codice può solo dire come , non perché o perché no . Hai bisogno di commenti per questo.

7

Code Complete, come detto, ha varie linee guida per la scrittura di commenti. In breve, è PDL e può essere riassunto come:

Descrivi il tuo intento, non quello che sta facendo il codice. Evitare di descrivere i dettagli dell'implementazione a meno che non si stia utilizzando un trucco o si stiano utilizzando implementazioni personalizzate. Ad esempio, usando i bit di spostamento per dividere, usando l'aritmetica del puntatore per accedere ai membri della classe o usando un allocatore di memoria personalizzato per alcuni oggetti in pool.
Scrivi prima lo pseudo codice (cioè i commenti), quindi scrivi il codice reale dopo aver finito di descrivere la routine / metodo / funzione. Il linguaggio utilizzato è di alto livello ma specifico, quindi può essere piuttosto dettagliato
Avere un'idea di ciò che il codice sta facendo anche prima di scrivere il codice
Avere commenti vicini al codice reale

L'obiettivo è evitare commenti non correlati a lungo termine che potrebbero essere obsoleti, ma avere commenti che riflettano l'intento e lo scopo del codice. L'uso di uno pseudo codice di alto livello aiuta anche a chiarire il tuo pensiero prima di scrivere l'implementazione.

C'è un link su GameDev.net [che spiega PDL] [1], nel caso in cui non desideri rintracciare il libro.

— Extrakun
fonte

5

Scrivi prima lo pseudo codice (ovvero i commenti) . Non potrei essere più in disaccordo. Non esiste un modo migliore per garantire che i commenti non corrispondano al codice. I nuovi programmatori (e chi chiede specificamente una guida per principianti) hackereranno e refatteranno le funzioni centinaia di volte prima che siano contenti di loro, il codice verrà spostato rapidamente, riscritto, rielaborato e alla fine, potrebbero hanno un'elegante soluzione funzionante, ma non assomiglierà affatto al loro pseudo codice iniziale. I commenti verranno spostati e aggiornati man mano che il codice funzionerà? Puoi scommettere che il tuo dolce bippy non lo farà. I miei due centesimi.

— Binary Worrier,

1

Inoltre, i commenti sullo pseudo codice ti diranno cosa dovrebbe fare il codice. Il codice dovrebbe dirtelo. Lo pseudo codice non ti dirà perché lo sta facendo. -1 amico, scusa, ma non posso essere d'accordo con il secondo punto, i tempi sono cambiati.

— Binary Worrier,

1

Non per discutere, ma più di una spiegazione: lo pseudo codice è di spiegare l'intento del codice che hai scritto. Significato, il commento non riguarda i dettagli di implementazione (come "Aggiungi x all'inizio dello stack") ma piuttosto ciò che il codice dovrebbe fare (come "Rendi la finestra visualizzata davanti a tutto il resto"). Come hai giustamente sottolineato, devi spostare i commenti con il codice. Non sono d'accordo con il codice, posso dirti cosa sta facendo il codice, sempre. Anche se, un commento utile / accurato (se riesco a scriverlo bene!) Fa molto. Alla fine, ancora IMHO.

— Extrakun,

3

Un metodo o una funzione chiamati showWindowOnTop(window)saranno sempre meglio di un commento della stessa natura, tutto questo è obsoleto e cattivo consiglio nel 2012. 1) I nomi di funzioni / metodi descrivono l'intento, 2) lo pseudo codice è un esercizio vuoto con le moderne catene di strumenti 3) I test ti dicono che cosa dovrebbe fare il codice prima di scriverlo, 4) un codice ben definito è meglio dei commenti che non corrispondono a un codice che non ha un buon nome

6

Seguo solo un principio semplice e comune: i tuoi commenti non dovrebbero dire cosa sta facendo il codice, ma perché lo stia facendo. L' articolo di Martin Fowler e il libro sul re-factoring e il codice Il libro completo contiene molte informazioni, ma purtroppo non è in forma sintetica per quanto ne sappia.

— Shahzeb
fonte

1

Il mio suggerimento sarebbe di scrivere un po 'di codice senza alcun commento, e poi andarmene. Torna tra un anno e leggilo. La parte che non capisci facilmente è la parte che avresti dovuto commentare.

— Kevin
fonte

1

Ah, sì ;-) Questo non è un consiglio particolarmente utile, però - forse questo avrebbe dovuto essere un commento?

— Cameron,

la parte che non capisci che avresti dovuto scrivere in parti più piccole con un nome migliore. Il motivo principale per cui i commenti vengono inseriti nel codice è che le funzioni / i metodi sono troppo lunghi e dovrebbero essere molti pezzi più piccoli autocompattanti.

0

Mi piace molto il modo in cui Evan Todd riassume la sua opinione sulle uniche utili categorie di commenti ( citando dal suo blog ):

Commenti che spiegano perché, piuttosto che cosa. Questi sono i più utili.

Commenti con poche parole che spiegano cosa fa il seguente grosso pezzo di codice. Questi sono utili per la navigazione e la lettura.

Commenti nella dichiarazione di una struttura di dati, spiegando cosa significa ogni campo. Spesso non sono necessari, ma a volte non è possibile mappare un concetto in modo intuitivo alla memoria e sono necessari commenti per descrivere la mappatura.

— Cameron
fonte