Quali informazioni deve contenere un buon commento (metodo / classe)? [chiuso]

Probabilmente è istruttivo che, tra i 99 Gotchas di C ++ Gotchas di Stephen Dewhurst, Gotcha # 1 sia Commenti eccessivi :

Comments are not inherently harmful — and are often necessary — but they must be maintained, and they're typically harder to maintain than the code they document. Comments should not state the obvious or provide information better maintained elsewhere. The goal is not to eliminate comments at any cost but to employ the minimal volume of comments that permits the code to be readily understood and maintained.

Leggere che cosa fa (che hai descritto) è utile - ma ciò che è ancora più utile è perché è richiesto e come si adatta allo schema di cose più grande .

L'autore è un'informazione assolutamente inutile da inserire in un commento. Nessun utente finale se ne preoccuperà mai, e se un capo tecnico deve scoprire chi ha scritto qualcosa, può usare il sistema di controllo di revisione (si si si utilizza un sistema di controllo di revisione, giusto?).

Gli ultimi sono solo se sono per tuoi usano e li rimuovi quando hai finito / prima di impegnarti nel repository. Altrimenti sono minuscole bombe a orologeria, pronte a esplodere di fronte alla prossima persona che mantiene quel codice e crea lavoro e distrazioni aggiuntivi. E tu sai sarà il momento in cui avranno 5 minuti per correggere alcuni bug di produzione critici.

Descrivere il metodo / classe, gli argomenti, il valore restituito e (a volte) le eccezioni sono utili, principalmente perché possono essere utilizzati per popolare il completamento del codice e / o le caratteristiche del codice (ad esempio IntelliSense, Code Assist, ecc.) , quando uso un'API di terze parti che non ho queste, ho sempre la sensazione di inciampare nell'oscurità. È fastidioso continuare a dover cambiare contesto tra l'editor di codice e il manuale - assumendo che sia un manuale. La cosa importante di questi particolari commenti è che diventano metadati , che è non il caso per le altre cose che hai menzionato.

fai crea documentazione con esempi di utilizzo, spiegazioni dettagliate, ipotesi, limitazioni, riferimenti a documenti di specifiche / requisiti, caratteristiche delle prestazioni e così via. Ma per favore mantieni quelli out dei commenti. Non è dove appartengono. I manutentori devono essere in grado di leggere il codice e non possono farlo in modo efficiente se ogni 1 riga di codice è accompagnata da 20 righe di commenti. Javadoc / XMLdoc tende a gonfiare il commento: il rapporto di codifica a volte quasi a 50/50; è già molto alto, e più di quello sarà intollerabile.

Ciò che odio di più del codice sorgente che ho visto nel corso degli anni sono i commenti, specialmente quelli prolissi che impediscono di leggere il codice. Per quanto mi riguarda, ci dovrebbero essere solo due motivi per avere commenti nel codice sorgente:

1. Il commento spiega qualcosa che non è visibile dal codice, e senza il commento il codice (o il suo effetto) è difficile da capire.
2. I commenti vengono utilizzati per la documentazione automatizzata (e anche quella ottiene più nel modo di qualsiasi altra cosa).

Se ti ritrovi a lasciare commenti dappertutto perché altrimenti il tuo codice sarebbe difficile da capire, allora è il momento di dare una buona occhiata al tuo codice e magari leggere questo libro .

Vorrei poter +2 la risposta di Gnawme a causa di questa affermazione:

Comments should not state the obvious ...

Il metodo di commento che ho trovato più efficace è questo:

• Se il codice non è banale, prima scrivo cosa voglio fare nei commenti come pseudo-codice. Mentre inserisco il codice effettivo, aggiorno i commenti per riflettere ciò che ho scritto.

Alla fine, i commenti non ti dicono necessariamente quale sia il codice , ma piuttosto ti dicono quale sia l' obiettivo del codice, e cosa io Stavo pensando mentre lo scrivevo.

Ma qualcosa di molto importante che è nascosto nella citazione di Gnawme è il principio che il tuo codice dovrebbe essere auto-documentante. È MOLTO meglio dare i nomi descrittivi di funzioni e variabili, piuttosto che cercare di sovvenzionare i poveri nomi con commenti esplicativi.

Il punto è di ridurre al minimo la quantità di conoscenze che lo sviluppatore deve tenere a mente in un dato momento per essere efficace . A volte, ciò potrebbe significare che hai dei nomi di funzioni lunghi, ma a chi importa? Un nome di funzione più lungo è migliore se elimina la necessità di saltare alla definizione (o ai metadati) per visualizzarne la descrizione. (A meno che tu non abbia una sorta di auto-completamento.)

Ho scoperto che dando nomi descrittivi a funzioni, parametri, ecc., spesso elimina la necessità di commentare ciò che la funzione fa e quali dovrebbero essere i parametri. Usando le buone convenzioni di denominazione, devi solo commentare quelle per i casi di palle dispari.

Infine, per favore non usare mai commenti per disabilitare il codice in modo permanente! se c'è una sezione di codice che stai rimuovendo dall'utilizzo, eliminala. Se ne hai mai bisogno, recuperalo dal tuo sistema di controllo del codice sorgente. Usa il tuo sistema di controllo del codice sorgente per le cose in cui è veramente bravo - come vedere chi ha scritto quella riga di codice, quando è stato scritto e cosa ha aggiunto / rimosso in una revisione.

Il miglior commento è quello che non scrivi.
I commenti non sono aggiornati rapidamente.
Ero solito scrivere pagine di commenti ma ora uso i seguenti principi:

• Dai un nome completo a classi, metodi e variabili con parole reali e non a abbreviazioni o lettere.

• Utilizza un sistema di controllo del codice sorgente (il mio preferito è git) per memorizzare nome utente, data di modifica, ecc.

• Se si fa un commento, non dichiarare l'ovvio in un commento. / * un nuovo commento * /

• Se il codice non è chiaro come è, prova a scrivere più test dettagliati per esprimere la funzionalità piuttosto che aggiungere commenti.