Voglio sapere se includere un commento di riepilogo del file all'inizio di ogni file è un buon modo per sapere cosa fa ogni file o c'è un modo migliore.
Un commento di riepilogo di alto livello all'inizio di qualsiasi unità di codice come un modulo, una classe o un pacchetto, che spiega lo scopo e / o le responsabilità dell'unità è sicuramente un modo utile di commentare in quasi tutti i linguaggi di programmazione che conosco. In molte lingue, non è raro (e in alcuni casi come Java è addirittura obbligatorio) avere una corrispondenza 1: 1 tra i file di codice e tali unità di codice, e lì la risposta è IMHO "sì, assolutamente".
Tuttavia, ti consiglio di utilizzare meglio un modello mentale di commenti di riepilogo per unità logica , non per unità fisica (file), questo spesso ha più senso. Tieni presente che molti linguaggi di programmazione consentono più unità per file o hanno determinate convenzioni per distribuire un'unità su un numero di file (ad esempio, suddividere una classe C ++ in un'intestazione e un file di implementazione).
Leggi altre domande sui tag comments documentation