Vorrei fornire anche decisioni di progettazione nei commenti. Voglio che i commenti sulla decisione di progettazione siano distinguibili dai commenti del contratto di funzione, all'esame sommario del codice sorgente.
Come si fa?
I commenti del contratto di funzione dovrebbero essere nei commenti javadoc piuttosto che nei commenti semplici (ad esempio, i commenti iniziano con /** ). Molti editor di evidenziazione della sintassi sono in grado di evidenziarli con un colore diverso rispetto ad altri commenti (ad esempio eclipse).
I commenti di cronologia / copyright / licenza di file devono essere limitati all'inizio del file.
I commenti sui lavori in corso e sulle attività devono essere taggati con una parola chiave appropriata (ad es. TODO o FIXME ) che ancora molti editor di evidenziazione della sintassi possono evidenziare (anche in questo caso eclipse è in grado di farlo).
Tutti gli altri commenti dovrebbero esistere per documentare le decisioni di progettazione, quindi possono essere facilmente distinti perché si tratta di commenti standard che non sono nella parte superiore del file.
Potresti provare a creare Tag personalizzati JavaDoc . Le tue decisioni di progettazione potrebbero avere un tag @why o qualcosa del genere. Ho sempre pensato che i commenti rispondessero alla domanda "Perché?" tendono ad essere il più utile.
Detto questo, sono d'accordo con @JohnBode e @BobDalgleish che non vuoi incollare pagine dei tuoi documenti di progettazione nel tuo codice, ma un sommario "TL; DR" di questi documenti potrebbe essere davvero utile a volte.