Quando dovrei aggiungere commenti al mio codice?

Question

• Quando lo sto scrivendo?
• Dopo aver ottenuto una parte (classe singola/funzione/if-elses)?
• Dopo che ho lavorato tutto?

Answer 1

La risposta breve

La risposta breve è ogni volta qualcosa è non evidente rispetto a cui sta per essere leggerlo. Se il suo codice è ancora in divenire, sei l'unico consumatore, solo commenti per te (ore e giorni). Pronto per il check-in per gli altri da provare - commenti per te e il tuo team (giorni e settimane, forse mesi). Pronto per un ampio rilascio - commenti per il pubblico immediato e futuro (mesi e anni). Devi pensare ai commenti come strumenti, non alla documentazione.

La risposta lunga:

• Quando sto scrivendo? - Yes
• Dopo aver ottenuto una parte fatto (classe/funzione singola/se-elses)? - Yes
• Dopo aver ottenuto il tutto lavorando? - Yes

Quando lo sto scrivendo? - Sì

goccia commenti ogni volta che si ha colpito un luogo in cui il codice non è immediatamente chiaro. Ad esempio, descrivere la classe quando il nome della classe non è chiaro o potrebbe essere interpretato troppo ampiamente. Un altro esempio è che se sto per scrivere un blocco di codice non ovvio, per prima cosa aggiungerò un commento che mi ricorda quello che voglio/ho bisogno. O se ho appena aggiunto del codice e ho capito subito che c'era un trucco, lascia un commento per ricordarti. Questi commenti sono commenti implementativi, meno per aiutare i futuri manutentori, ma piuttosto per aiutare te stesso nel processo di codifica.

Drop FIXME - explanation e TODO explanations promemoria mentre si procede.

Codice è ancora in evoluzione, quindi non sono ancora documentare ogni e tutto il metodo e il parametro.

Dopo aver ottenuto una parte fatto (classe/funzione singola/se-elses)? - Yes

Quando sono ragionevolmente fatto con un metodo o una classe, ora è il momento di rivederlo. Insieme con il controllo ambiti di metodi, i metodi di ordinamento, e altro codice di pulizia per migliorare la comprensibilità, ora è il momento di cominciare a standardizzare contro i vostri standard di squadra. Considerate ciò che i commenti sono necessità in base al pubblico sarà rilasciato a (futuro che fa parte del pubblico troppo!) Se la classe dispone di un blocco di testa? Ci sono condizioni non ovvie in base alle quali questo metodo non dovrebbe essere chiamato? Questo parametro ha alcune condizioni su di esso, ad es. non dovrebbe essere nullo?

Verificare le FIXME e TODO articoli - è ancora valido? Qualunque cosa dovresti affrontare ora prima di andare avanti?

Questi sono ancora note per voi e la vostra squadra, ma l'inizio di note standardizzati per manutentori future.

Dopo aver ottenuto l'intera faccenda di lavoro? - Yes

Ora è il momento di rivedere tutto e finalizzare i commenti in base ai propri standard.

Tutti gli articoli FIXME e TODO indirizzati (riparati o acquisiti come noti)?

Queste note ora sono per i manutentori futuri.

Ora il piccolo sporco segreto

Di più non è sempre meglio. Come unit tests, è necessario bilanciare l'utilizzo dei vostri strumenti costi vs benefici di pesatura.Il fatto è che un programmatore può solo digitare così tante linee fisiche all'ora - quale percentuale dovrebbe essere un commento? Una bassa percentuale significa che ho un sacco di codice, ma è confuso e difficile da capire e usare correttamente. Un'alta percentuale significa che, in un'ora in cui qualcuno modifica la firma di un metodo o ridefinisce un'interfaccia, tutto il tempo è dedicato a commentare completamente ogni parametro di questi metodi.

Trova la percentuale giusta in base alla stabilità del codice, per quanto tempo vivrà e quanto ampiamente verrà rilasciato. Non ancora stabile - commenti minimi per aiutare te e il tuo team. Stabile e pronto per il progetto - completamente commentato. Rilascio pubblico? - completamente commentato (ricontrollare!) con i diritti d'autore (se applicabile). Man mano che acquisisci esperienza, regola la percentuale.

Answer 2

Questa è una questione di stile. Personalmente, mi piace scrivere commenti durante la codifica, non dopo. Perché lo lascio a dopo, di solito mi sento pigro e non li scrivo affatto. Detto questo, a volte è utile esaminare un pezzo di codice completo, capire cosa non è ovvio dal codice stesso e documentarlo. In particolare, le parti in cui vengono fatte le ipotesi.

Answer 3

Non si dovrebbero mai aggiungere commenti, non si tratta di aggiunte. I commenti fanno parte del codice: li usi quando ne hai bisogno. Chiedere quando dovresti aggiungerli è come chiedere quando devi aggiungere funzioni o classi. Anche se ci penso, ricordo di aver fatto un corso di consulenza al programma all'università dove ho lavorato per uno degli studenti con circa 1000 righe di Pascal, senza funzioni. Quando ho chiesto perché non aveva usato le funzioni, la sua risposta è stata "Le aggiungerò più tardi, una volta che ho funzionato."

Answer 4

Questo è soggettivo, ma a volte è meglio aggiungerli prima del codice effettivo, ad es. quando si implementa un algoritmo che ha passaggi chiaramente definiti. In questo modo è difficile perdere i passaggi.

Answer 5

I commenti devono riflettere perché si stanno facendo le cose come si fa, non quello che fa. Il più delle volte chi legge il tuo codice può leggere quello che fa.

È necessario spiegare le cose che non è possibile ridurre dal codice.

Answer 6

Aggiungo commenti durante la scrittura di un codice che non è facilmente comprensibile. Trovo che se non lo faccio immediatamente, allora viene dimenticato. Io (o più probabilmente qualcun altro) dedico più tempo a capire cosa ho fatto di quanto non sarebbe stato necessario per scrivere il commento.

Per essere più precisi, commentare immediatamente dopo la scrittura del codice è la via migliore per garantire che i commenti vengano effettivamente scritti.

Answer 7

Tendo a mettere i commenti di base mentre sto andando, solo per ricordare a me stesso cosa stavo pensando nel momento in cui l'ho scritto (cioè perché l'ho scritto in quel modo). Lo faccio soprattutto se si tratta di codice che potrebbe sembrare sbagliato ma in realtà giusto, o codice che presenta una condizione di razza intrinseca di cui non mi importa, o codice che potrebbe non essere ottimale ma è un modo rapido per ottenere qualcosa lavorando, così che anche una decina di minuti più tardi, quando torno a guardarlo, vedo che ho già pensato al problema e non devo sprecare cicli cerebrali.

Quando il codice è più completo, tornerò spesso e rivedrò i commenti che ho scritto e poi penserò se penso ancora che le decisioni prese siano ragionevoli, e se le cose potrebbero essere fatte meglio. Inoltre, espanderò spesso il commento di base in un commento più lungo che è più utile ad altre persone quando vengono a mantenere il codice; Solitamente salvataggio l'espansione dei commenti fino alla fine perché molti dei commenti di base del tempo vengono cancellati durante il refactoring, quindi scrivere un commento lungo è una perdita di tempo finché non sai che lo manterrai.

In breve, scrivere i commenti di base mentre si procede e quindi migliorarli man mano che il codice diventa più stabile.

Oh, e anche, ogni volta che rivedi un po 'di codice esistente e sei colpito da un WTF ?! momento, ma poi rendersi conto che il codice è effettivamente decente, mettere un commento per salvare te stesso e il tempo della prossima persona quando lo guardano in futuro.

Answer 8

Suggerisco di scrivere commenti ogni volta che si modifica qualsiasi codice, mentre lo si modifica. Secondo Robert C. Martin nel Clean Code, uno svantaggio dei commenti è che il codice può cambiare senza che i commenti vengano aggiornati, rendendo i commenti non solo inutili, ma pericolosi. Per ridurre questo problema, se si utilizza utilizzare commenti (poiché non è possibile esprimersi nel codice stesso), assicurarsi di aggiornarli ogni volta che si aggiorna il codice.

Answer 9

Uno svantaggio di aggiungere commenti in seguito è che un sacco di volte che sarà non solo essere fatto, a causa di pigrizia, altre attività, ecc

Se si trova si può sempre tornare indietro e aggiungere i commenti appropriati, senza qualsiasi problema, quindi con tutti i mezzi farlo, ma altrimenti fare uno sforzo cosciente per aggiungerli mentre stai codificando o prima di codificare una sezione può essere un modo per assicurarti di non lasciare il codice non commentato.

Answer 10

Inserire un commento OVUNQUE il programmatore che legge il codice, potrebbe generare un momento WTF.

Se vi trovate a commentare ogni riga, forse avete bisogno di dare un'occhiata a cercare di migliorare il vostro codice con affermazioni più semplici ed eleganti.

Answer 11

La domanda deve essere, quando devo aggiungere il codice ai miei commenti?

La mia pratica è di scrivere la funzionalità di un modulo/oggetto/funzione come una serie di commenti. Non commenti come "aggiungi uno al contatore". Commenti di livello più elevato come "elenco di ordinazioni per numero di conto". I commenti dettagliati sono praticamente ridondanti con il codice. Quindi evito quelli a meno che non stia scrivendo un algoritmo molto complicato. Una volta che ho la funzionalità "progettata" nei commenti, mi comporto come un compilatore umano e aggiungo il codice dopo ogni riga di commenti.

Provalo e facci sapere come funziona!

Answer 12

Personalmente, tendo a scrivere commenti per riepilogare il codice laddove necessario, spesso prima di scrivere il codice e di salvare i WTF. Li tratto esattamente come note - di cose da fare, cose che ho fatto in questo modo, o farò in questo modo, e in quanto tali vengono inserite quando e dove sento il bisogno per loro.

Answer 13

Prima di dimenticare quali specifiche e design il codice è necessario per implementare. Prima di dimenticare che qualche sfortunato programmatore dovrà leggerlo in seguito. Prima di dimenticare che lo sfortunato programmatore potrebbe benissimo essere te.

Answer 14

Quando si fa qualcosa di non banale, come lo stai scrivendo.

Answer 15

Hai dato un sacco di casi nella tua domanda. Penso che dipenda da cosa stai facendo in quel momento.

Se si sta scrivendo una funzione o una classe, i commenti sono un modo per dichiarare cosa dovrebbe accadere con la funzione. Cose come le variabili di input, il tipo di output, il comportamento speciale, le eccezioni, ecc. IMHO quel tipo di commento dovrebbe essere scritto prima che il codice effettivo venga avviato, nella tua fase di "progettazione del codice". La maggior parte delle lingue ha pacchetti che elaborano questo tipo di commenti nella documentazione (javadoc, epydoc, POD, ecc., In modo che gli utenti possano leggere le cose.

Se stai facendo un po 'di lavoro sul codice, penso che sia OK aspetta fino a quando non hai lavorato per inserire un commento che descrive trionfalmente la tua soluzione di lavoro.Questo tipo di commento verrà letto da un revisore di codice

Quindi, come altri hanno detto, si vuole evitare WTF momenti, da soli o da altri.Una volta ho avuto un attaboy per un commento che ho fatto una volta in un progetto open-source.Il commento era "Sì, davvero voglio = e non == su quella linea."

Answer 16

A quando decidi una decizione arbitraria che w potrebbe essere difficile da capire. B. Ogni cosa che dovresti ricordare mentre scrivi il codice C. all'inizio di un programma spiega la logica e usa il consiglio - invece di commentare molto usi nomi lunghi per funzioni e var che spiegano veramente cosa la funzione fa o ciò che la variabile rappresenta.

Answer 17

Principalmente quando si scrive quel codice. Puoi andare lì dopo la funzione/blocco/qualsiasi cosa sia fatta e organizzare i tuoi commenti sulla mente fresca. La maggior parte delle cose che scriviamo durante la codifica non sono significative in seguito.

Answer 18

All'inizio della mia carriera ho aggiunto commenti a quasi tutte le linee di codice, come forse si potrebbe fare in un programma ASM. Col passare del tempo mi sono imbattuto in molti dei problemi menzionati qui. E 'stato un orso mantenere ciò che ha portato a non aggiornare i commenti e poi diventano stantii al meglio, di solito ammuffiti.

Ritengo che il numero di commenti dovrebbe riflettere quanto sia complesso o non ovvio il codice stesso. In un ambiente più impegnativo, come ASM, probabilmente avrai bisogno di più commenti per capire cosa sta succedendo. Nei linguaggi più moderni come C# non dovresti aver bisogno di molti commenti nella maggior parte dei casi.

Generalmente utilizzo strumenti che valutano la complessità dei miei metodi in C#. Quelli che sono in cima alla scala della complessità vengono prima rifatti. Poi, quando sono soddisfatto della complessità rimanente e ho ancora un codice che non è ovvio, o anche più importante, sembra ovvio ma fa qualcosa di diverso, quindi aggiungo un commento su di esso.

Answer 19

Si dovrebbe provare a scrivere commenti PRIMA di scrivere qualsiasi codice.ad esempio

public string getCurrentUserName() { 
    //init user database repository 


    //retrieve logged in user 


    //return name if a user is logged in, otherwise return null 

} 

commenti di scrittura prima di codice, ti aiuta a imparare come strutturare il codice senza realmente codifica e rendersi conto che si dovrebbe avere fatto in un altro modo. È anche un buon modo per visualizzare rapidamente una soluzione pulita a un problema complesso senza impantanarsi nell'implementazione. È anche un bene perché se vieni interrotto, quando torni al tuo lavoro puoi tornare subito ad esso, invece di ridefinire ciò che hai fatto e ciò che devi fare dopo.

Non adatto a tutte le situazioni, ma spesso una buona opzione!