Quali sono i vantaggi dell'utilizzo dei commenti

Pulisci codice ha un intero capitolo sui commenti, quando sono buoni e quando non lo sono. Inoltre un sacco di consigli pratici su come scrivere codice che non ha bisogno di così tanti commenti.

Modifica: Anna ha chiesto un riepilogo e, dal momento che stavi chiedendo solo ragioni pro-commento, il riepilogo del sommario del sommario dei buoni motivi per utilizzare i commenti del libro include:

• Note legali, come i diritti d'autore
• Quando non è possibile utilizzare un nome di funzione per spiegare qualcosa
• Il tuo intento dietro una decisione
• Chiarimento del codice che non puoi modificare, come i risultati di una chiamata alla libreria
• Avviso di conseguenze
• TODO (in misura ragionevole)
• Amplifica l'importanza di qualcosa apparentemente insignificante
• Javadoc in API pubbliche

C'è un paio di paragrafi o più su ciascuno di questi argomenti, con esempi di codice reali inclusi per l'illustrazione. È davvero una lettura utile.

Nella massima misura possibile, il codice dovrebbe essere auto-descrittivo. Cioè, dovrebbe essere scritto abbastanza chiaramente per essere comprensibile senza commenti. Ne risulta un codice che è più gestibile da altri ed elimina la ridondanza causata dai commenti (quando si modifica il codice, è necessario aggiornare anche i commenti).

Tuttavia, i commenti sono fondamentali per descrivere le relazioni tra gli oggetti codice e le diverse parti del sistema e come utilizzare correttamente il codice una volta scritto. In altre parole, come tutti i pezzi della tua applicazione o libreria lavorano insieme. Gli sviluppatori che sostengono di non scrivere alcun commento costruiscono sistemi ampi, opachi e indecifrabili perché non apprezzano appieno questo punto.

Uncle Bob Martin, nel suo libro Clean Code, sostiene l'uso di commenti per i seguenti scopi:

1. Spiegazione di intenti
2. Chiarimento
3. Avvertenze
4. Amplificazione
5. TODOs

Come minimo, i commenti dovrebbero descrivere cosa fa ogni membro pubblico e come usarlo, e spiegare tutti i parametri e restituire i valori con intervalli accettabili (ad esempio tra 1 e 1000) per ciascuno.

Quando analizzi un pezzo di codice non puoi dire se è corretto o meno a meno che tu non sappia cosa è supposto fare. Tu puoi solo dire cosa fa. Un buon commento può dirti qual è il codice dovrebbe portare a termine. Se è ridondante, è una buona cosa perché significa che il codice soddisfa il suo obiettivo.

I commenti possono anche dirti perché lo fa.

'abbiamo mantenuto le linee sotto 128 byte perché c'è un'eredità componente che si rompe quando superano quello '

Qualcuno che potrebbe obiettare di "metterlo nel test unitario invece di un commento "non riesce a capire che deve quindi essere commentato nel unit test, e che quando qualcuno cambia il valore e la regressione il test fallisce, scoprirà che ha sprecato il suo tempo perché il commento che doveva vedere era nel posto sbagliato.

Vorresti proporre questo?

'write_but_do_not_exceed_the_limits_that_the_legacy_component_can_handle ()'

'La buona nomenclatura è sufficiente' è ingenua, un'idea che viene da persone pigre chi non ha mai imparato come commentare correttamente in primo luogo.

i commenti non riguardano il modo in cui un'applicazione funziona, ma il motivo per cui questa funzione raggiunge i suoi obiettivi usando X. Se il codice è scritto male e non ha nomi di funzione che descrivono ciò che fanno, quindi aggiungendo una linea per ogni funzione fare questo sarebbe un uso utile dei commenti come cerotto. Mi sembra che tu non capisca come leggere il codice se non riesci a capire come funziona. Se intendevi ciò che fa il codice, questo dovrebbe essere spiegato in documenti esterni come casi d'uso o flussi di processo e schemi di progettazione. Sembra anche che ti stai avvicinando all'apprendimento del codice dall'angolo sbagliato. A meno che il tuo codice non sia in una singola funzione lunga 50000 righe, la lunghezza è irrilevante, ti fa rimanere bloccato su quanto è grande. Si impara un sistema di grandi dimensioni in parti, si sceglie un livello / classe e si impara cosa fa in relazione al progetto e come funziona, quindi ne sceglie un altro e lo ripete. È anche utile per capire il flusso di alto livello di ciò che fa la tua app, prima di provare ad apprendere i dettagli di implementazione di basso livello.

Cercare di imporre l'uso dei commenti per il codice aggiunto può essere una buona causa, ma cercare di tornare indietro e aggiungere commenti al codice esistente è un'iniziativa inutile, semplicemente non funziona perché la conoscenza di ciò che dovrebbe essere in quei commenti è andato perché nessuno è nella mentalità dello sviluppatore in quel momento.

Punti utili dei commenti:

• Identifica il motivo per cui esiste un metodo per eseguire X.
• Identifica quali sono gli input / output di un metodo in modo che sia chiaro se i parametri devono essere ottimizzati, ad es. se si passa in un numero di millisecondi o secondi possono esserci modifiche da apportare.
• Identificare gli effetti collaterali di un metodo, ad es. ci sono altre cose che potrebbe desiderare di conoscere oltre alle sue intenzioni iniziali? (Questo dovrebbe essere raro ovviamente)
• Metti una nota nel codice che qualcosa ha un "odore di codice" e vale la pena considerare il refactoring in qualche modo.
• Inserisci una nota nel codice per spiegare perché un kludge è stato spinto nel punto in cui si trova, che è piuttosto simile al punto precedente.

Una cosa che non ho visto menzionato non è solo il motivo per cui hai fatto qualcosa, ma un riferimento al numero di attività del sistema di tracciamento dei bug o di gestione dei progetti che ti ha fatto fare la modifica. Non per tutto, ma ci è stato chiesto a tutti di cambiare il fatto che ci fosse un lungo processo decisionale (documentato nel sistema di gestione del progetto) che porta a ciò che sembra estraneo ad essere una scelta strana nel codice ma che il deverloper aveva ragioni complesse per fare quel modo o una richiesta di cambiamento che sentivamo sarebbe tornato a morderci più tardi. Conoscendo fin da subito il numero di attività da cercare nel PM o il sistema di tracciamento dei bug può aiutare immensamente quando in seguito per vedere se il requisito è realmente cambiato o se il nuovo requisito non sta prendendo in considerazione il vecchio requierment. Sono state disattivate diverse modifiche future negative perché sono stato in grado di trovare rapidamente il motivo per cui l'applicazione ha funzionato nel modo in cui è stata eseguita.

Hai pensato di utilizzare Javadoc (o doxygen o altri strumenti simili)? In tal caso, puoi usare (anche) l'argomento che può generare un riferimento facile da consultare delle API delle applicazioni (e persino dei diagrammi) in HTML, accessibile a tutti.

Inoltre, i test unitari e i pattern per denominare metodi, variabili e altri aiutano molto.

Sono già state fornite diverse risposte e ne esistono altre se cerchi questo sito. Quello che voglio portare la tua attenzione è il seguente:

1. Prima di chiedere alle persone di fare commenti - Preparare una serie di regole ed esempi di come dovrebbero apparire i commenti (formato), lunghezza, contenuto, ambito e quando usarli.

2. Evita di descrivere il più possibile le regole aziendali all'interno dell'applicazione. Il codice può fare riferimento a regole aziendali in documenti esterni, ma non dovrebbe dichiararli verbalmente all'interno del codice.