Guida per principianti per scrivere commenti?

Dovresti essere consapevole della più grande debolezza dei commenti: diventano stantii. Cioè, mentre il codice cambia, gli sviluppatori aggiornano raramente i commenti per rimanere sincronizzati con il codice. Questo significa che non puoi mai fidarti di loro e che alla fine continuerai a leggere il codice. Per questo motivo, il tuo codice dovrebbe essere auto-documentante. Dovresti scegliere la tua funzione e i nomi delle variabili in modo tale che il codice sia simile alla prosa.

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

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

Il codice completo, come detto, ha varie linee guida sulla scrittura di commenti. In breve, è PDL e può essere riassunto come:

1. Descrivi il tuo intento, non quello che sta facendo il codice. Evitare di descrivere i dettagli di implementazione a meno che non si stia utilizzando qualche trucco o si stiano utilizzando implementazioni personalizzate. Ad esempio, utilizzando i bit di spostamento per dividere, utilizzando l'aritmetica del puntatore per accedere ai membri della classe o utilizzando un allocatore di memoria personalizzato per alcuni oggetti raggruppati.

2. Scrivi prima lo pseudo codice (cioè i commenti), poi scrivi il codice reale dopo aver terminato di descrivere la tua routine / metodo / funzione. Il linguaggio utilizzato è di alto livello ma specifico, quindi può essere piuttosto dettagliato

3. Avere un'idea di cosa sta facendo il tuo codice anche prima di scrivere il codice

4. Hai commenti il più vicino possibile al codice attuale

L'obiettivo è evitare commenti non correlati a lungo termine che potrebbero essere superati, 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 tu non voglia rintracciare il libro.

Seguo solo un principio semplice e comune: i tuoi commenti non dovrebbero dire cosa sta facendo il codice, ma perché lo sta facendo. Martin Fowler Articolo e Prenota su Re-factoring e Il libro completo di codice contiene molte informazioni, ma purtroppo non è in forma riassuntiva per quanto ne so.

Il mio suggerimento sarebbe quello di scrivere del codice senza commenti di sorta, e poi allontanarlo da esso. Ritorna in un anno e leggilo. La parte che non capisci facilmente è la parte che dovresti aver commentato.

Mi piace molto come Evan Todd riassuma la sua opinione sulle uniche categorie di commenti utili ( citando dal suo blog ):

• Comments explaining why, rather than what. These are the most useful.
• Comments with a few words explaining what the following giant chunk of code does. These are useful for navigation and reading.
• Comments in the declaration of a data structure, explaining what each field means. These are often unnecessary, but sometimes it's not possible to map a concept intuitively to memory, and comments are necessary to describe the mapping.