I commenti del codice dovrebbero spiegare il flusso di controllo?

A mio parere, i commenti dovrebbero spiegare tutto ciò che non può essere reso evidente dal codice effettivo, e qualsiasi documentazione esterna dettagliata di cui hai bisogno dovrebbe essere generata da quei commenti (presumibilmente come parte del tuo sistema di build / deployment automatizzato). / p>

Chiarire a cosa serve una classe o funzione, quali problemi è stato creato per risolvere e dove si inserisce nel programma nel suo insieme probabilmente ci sono cose che valgono la pena di commentare. Assicurati che il commento sia proprio al di sopra di qualsiasi cosa stia parlando, e non è più lungo di quanto dovrebbe essere, dal momento che vogliamo rendere più facile per gli sviluppatori futuri mantenere il codice e i commenti sincronizzati. Un commento obsoleto è in genere peggiore di niente.

"Flusso di controllo" normalmente significa cose come l'uso di istruzioni if e loop, che non dovrebbero quasi mai richiedere commenti, ma sembra che quello che stai cercando di chiedere sia più simile a un grande commento in cima a main () che riepiloga quali funzioni di primo livello vengono chiamate in quale ordine e perché; questo andrebbe bene se si può garantire che rimanga aggiornato (che è più facile a dirsi che a farsi).

Per la visione concettuale di livello molto alto di come funziona il tuo programma, probabilmente dovresti fare affidamento su un breve file scritto a mano al di fuori del codice sorgente (come il file README.md su un repository di Github). Ma una volta che le persone conoscono le informazioni di base, sì dovrebbero essere in grado di immergersi in qualsiasi parte dell'albero sorgente e capire cosa succede dal codice e dai commenti che vedono di fronte a loro.

No.

Se le persone non sono in grado di leggere il codice e capire cosa sta facendo il codice, questo è un segno che il tuo codice è mal progettato, eccessivamente complesso o mal chiamato (o una combinazione di questi). I commenti non risolvono questi problemi, ma li esacerbano solo.

Usa i commenti per descrivere perché il codice sta facendo cose strane.

Una documentazione più convenzionale è migliore per descrivere l'architettura / l'applicazione più ampia.

I commenti non dovrebbero spiegare come funziona il codice. Il codice è lì per spiegare come funziona. Se l'implementazione viene modificata, il commento diventa errato.

Per lo più i commenti dovrebbero spiegare qual è lo scopo del codice. Ciò consente di modificare l'implementazione nel tempo senza invalidare il commento. Cambiare lo scopo del codice è raramente una buona idea.

Per le interfacce pubbliche potresti voler fornire una documentazione estraibile per la macchina che spieghi:

• Qual è il suo scopo e cosa viene restituito.
• Descrivi lo scopo e i valori validi sono per ciascun parametro.
• Probabilmente spiega come si prevede che la funzionalità possa / potrebbe essere utilizzata.

Esistono vari strumenti che estraggono la documentazione dai contenuti. Java ha javadoc, che estrae alcuni commenti e crea un albero di documentazione per un pacchetto di classi.

I buoni nomi possono essere una documentazione sufficiente. Evita i nomi che spiegano come viene implementata la funzionalità.

Se il codice è stato ottimizzato, potrebbe essere opportuno includere un commento che spieghi perché il codice è stato modificato e quali sono i risultati. Ciò dovrebbe ridurre la possibilità che il codice venga refactored per rimuovere l'ottimizzazione. Allo stesso modo, se è richiesto un particolare algoritmo, sarebbe opportuno un commento che spieghi il requisito. Questi due commenti potrebbero essere in disaccordo poiché un algoritmo più accurato potrebbe essere un algoritmo più lento.

I commenti sulle correzioni dei bug dovrebbero essere nel controllo della versione. Questi dovrebbero spiegare perché il cambiamento è stato richiesto / fatto piuttosto che come è stato implementato.