When To Code Codice (L'altro "Quando")

Question

Ieri stavo passando attraverso un mio codice che non aveva senso per me in un primo momento (scritto meno di un mese fa). Quando l'ho capito, ho rapidamente aggiunto dei commenti per evitare l'esercizio. Questo mi ha fatto pensare che, se avessi commentato il codice come, l'ho scritto, i miei commenti potrebbero non aver aiutato un secondo "io" a decifrare il codice.

Quando nella vita del codice è meglio aggiungere commenti? Se la risposta è che dipende, da cosa dipende?

Nota: sto chiedendo esperienza- o, meglio ancora, le risposte della letteratura basata, dà fastidio solo rispetto "pensieri sul tema" Inoltre, si prega di notare che questa domanda assume che è necessario codice di commento (a volte, a volte o sempre).

Answer 1

In linea di principio, si dovrebbe commentare il codice mentre lo si scrive, ma, come la propria esperienza ha appena dimostrato, spesso si è troppo vicini al problema per scrivere i migliori commenti. Secondo la mia esperienza, questo è un argomento forte per una qualche forma di revisione del codice, sia che la revisione continua della programmazione di coppia o qualcosa di più formale, a seconda dei casi - "commenta che in modo così approfondito in così e in modo" dovrebbe essere previsto esito della revisione da parte di altri occhi.

Answer 2

Si dovrebbe sempre commentare il codice che spiega perché un modulo fa qualcosa, non cosa (questo è ciò che il codice è per :)) Tutto ciò che non è chiaro sul motivo per cui qualcosa sta accadendo deve essere commentato. Il codice dovrebbe essere scritto abbastanza bene da essere capito da solo.

Ho intenzione di chiarire un po 'il mio ultimo commento. A volte penso che sia giusto commentare quale codice sta per fare (so che questo contraddice la mia precedente affermazione). Ci sono cose nel codice che alcune persone non saranno in grado di capire. Non è che il codice sia scritto male, è che i concetti che usano sono avanzati e le persone si confondono. Sto pensando a cose come la creazione ricorsiva di alberi, grafici, ecc. Cose che possono essere chiare per te, ma che potrebbero causare problemi agli altri. Penso che ciò avvenga caso per caso e dipende dal team con cui si sta lavorando.

È necessario scrivere sempre i commenti PRIMA di scrivere il codice. Dovresti sempre sapere esattamente cosa sta per fare qualcosa e perché prima di decifrarlo.

Answer 3

Penso che il problema con i commenti sia meno sul "quando" e più sul "come". Se le persone commentavano correttamente il codice in primo luogo, allora il "quando" non avrebbe importanza - se qualcuno potesse tornare al codice in qualsiasi momento e capire cosa si supponeva dovesse fare, allora i commenti sono ben fatti. Questo ovviamente va di pari passo con la scrittura di un codice buono e leggibile.

Ci sono un sacco di domande che fluttuano intorno allo stack overflow su come scrivere buoni commenti, (ad esempio Are there standard formats for comments within code?) ma fondamentalmente sta andando a differire tra organizzazioni e stili personali. L'obiettivo finale dei commenti è di aiutare a comprendere il codice.

Fintanto che si scrivono correttamente i commenti, quando li scrivi non dovrebbe fare alcuna differenza.

Answer 4

Ho ottenuto risultati migliori direttamente o poco dopo averlo scritto. Cioè, non mentre si codifica (tende a distrarmi), ma almeno prima di commettere una modifica o unirle di nuovo nel ramo principale.

Se non lo faccio direttamente, tendo a dimenticarlo oa preoccuparmene di meno. Detto questo, se rivisito il codice e noto che potrebbe utilizzare alcuni commenti, li aggiungo comunque.

Aggiornamento: altri fanno buoni punti di scrivere commenti prima di partenza, ma la mia esperienza è che essa lascia dietro di sé una scia di pseudocodice commentato-out (che è terribilmente distrazione e inutile).

Answer 5

Evito di commentare il codice, preferendo scrivere codice abbastanza chiaro da non richiedere commenti. Ma a volte hai alcune "conoscenze tribali" incorporate nel codice. In tal caso è necessario spiegare perché il codice fa quello che fa e non tanto quello che fa il codice.

Answer 6

La mia regola generale è: codice il più trasparente possibile (seguendo il tema del "codice di autocertificazione"). Quando quello che stai facendo non è auto-esplicativo, commentalo. Ad esempio, non è necessario commentare i termini di deallocazione. Effettuare il looping di un array per eseguire il lavoro sui suoi membri dovrebbe - non importa quanto sia semplice il ciclo, è più veloce e più facile capire un commento di codice piuttosto che attraversare il ciclo e assicurarsi che non stia facendo nulla di inaspettato.

Per quanto riguarda QUANDO, preferisco "prima di scrivere il codice". Non lo farai giustizia dopo che il codice è stato scritto. Scrivi un commento che spiega le tue intenzioni, quindi esegui quelle intenzioni nel codice. Controlla il commento per assicurarti che sia ancora pertinente e che tu sia GTG.

Si consiglia vivamente Code Complete come una risorsa molto solida su quando e come commentare il codice (tra le altre migliori pratiche).

Answer 7

Penso che sia necessario commentare il proprio codice ogni volta che sta facendo qualcosa che non è completamente ovvio dal codice sorgente stesso. Ovviamente questo dipenderà da molti fattori, uno dei quali è il tuo pubblico.

Quando scrivo codice che so che sarò l'unico con cui lavoro, i miei commenti tendono ad elencare solo i posti in cui c'è un comportamento strano o codice che ho preso da qualche altra parte. Il più delle volte, il codice che ho scritto in passato ha perfettamente senso per me solo guardando la fonte.

Detto questo, quando scrivo un tutorial che spero che molte persone leggeranno, commenterò ogni sezione del codice e spiegherò che cosa fa ogni riga al di fuori delle strutture di programmazione di base. In questo modo, quando stanno leggendo il codice cercando di capire cosa sta succedendo, la spiegazione inglese completa è proprio sopra la linea del codice stesso.

Answer 8

Ho intenzione di cantare di nuovo la stessa canzone: do a "Clean Code" (Robert C. Martin) una lettura. Come ho sostenuto in this post

C'è un paio di capitoli eccellenti sulle convenzioni di denominazione, leggibilità del codice e anche COMMENTI. Consigli ben supportati su come e quando scrivere commenti nel tuo codice.

Answer 9

Di solito scrivo alcuni commenti rapidi su aree difficili mentre sto andando, e poi quando finisco un pezzo importante (una classe completata, per esempio), passo e commenta tutto più completamente, assicurandomi che qualsiasi commento Ho già fatto riflettere la realtà attuale. Uno dei peggiori scenari è commentare qualcosa, quindi apportare un cambiamento significativo e non modificare i commenti per riflettere tale cambiamento. In molti casi è peggio che non commentare perché potresti fornire informazioni false al lettore del tuo codice e spesso crederanno ai commenti sul codice stesso.

Answer 10

Quando qualcuno lo esamina per te, e loro dicono "Non capisco questo po '".

Answer 11

ho davvero vi incoraggio a leggere questo libro: Code Craft: The Practice of Writing Excellent Code

C'è un intero capitolo su questo argomento.

Ecco alcuni concetti chiave da quel capitolo:

• imparare a scrivere abbastanza commenti, e non di più. Favorire la qualità, non la quantità.
• Trascorri il tuo tempo scrivendo il codice che non ha bisogno di essere sostenuto da tonnellate di commenti.
• I buoni commenti spiegano perché non come.
• Quando ti ritrovi a scrivere commenti densi per spiegare, fai un passo indietro. C'è un problema più grande da risolvere?
• ecc

Answer 12

Se hai intenzione di commentare più tardi, probabilmente non commentare affatto.

Answer 13

Sono d'accordo con i ragazzi di cui sopra riguardo al commento "PRIMA" del codice. Questo ti aiuterà a ricordare lo scopo della funzione/metodo/blocco di codice. È facile seguire le tracce quando si codifica e si dimentica l'intenzione originale. Ad esempio se stai scrivendo una funzione getFoo() e non riesci a ricordare cosa dovrebbe restituire, allora sei ritardato. Tuttavia, se si sta scrivendo una funzione che esegue diversi calcoli sgradevoli mentre si scorre attraverso più set di dati, i commenti potrebbero essere di aiuto.

Answer 14

Ho sentito parlare (ma non riesco a trovare) il "Principio della Necessità" rispetto al campo dell'Educazione. Per dirla chiaramente, gli studenti imparano quando e cosa hanno bisogno di imparare. Esistono analogie con TDD (solo codice di scrittura con un test fallito per dimostrare la sua necessità) e Lean (Just In Time, in particolare). Penso che ciò che hai dimostrato con il commento di ieri fosse l'applicazione del Principio della Necessità a commentare, e penso che il modo in cui hai proceduto, e il tuo programma, sia andato bene.

Nel momento in cui scriviamo un metodo, siamo consapevoli di ciò che è importante in merito alle questioni immediate di interesse; come si inserisce nell'altro codice che stiamo scrivendo oggi, quali falsi percorsi abbiamo preso mentre lo scrivevamo, perché lo abbiamo scritto in primo luogo. Ma noi (spesso) non sappiamo quello che vorremmo sapere su di esso in futuro, anche solo un mese dopo. Quando abbiamo bisogno di sapere qualcosa di più su di esso, e quando è doloroso acquisire quella conoscenza - è un buon momento per registrare quella nuova conoscenza.

Non sto dicendo che non dovresti scrivere commenti prima/durante/immediatamente dopo aver scritto il codice: è una questione di standard e stile personale e di squadra. Ma quando ti rendi conto di una carenza di documentazione, è un buon momento per correggerlo.

Answer 15

io non sempre arrivare scrivere questo perfettamente, ma idealmente, preferisco

• Stub fuori il codice e aggiungere commenti su ciò che metodi/classi dovrebbero fare
• test di scrittura per la loro copertura (TDD)
• torna gli stub e compilare il codice di superare le prove, i commenti che vi aiuteranno a ricordare ciò che è necessario fare

ho trovato che questo scorre abbastanza bene per me. Inoltre, non mi sono collegato a nessuna "letteratura" sull'argomento perché penso che qualsiasi letteratura sui commenti probabilmente sarà sciocca, o che cosa ha funzionato per qualcun altro. Potrebbe o potrebbe non funzionare per te.

Modifica: ho scoperto che quando scrivo commenti molto prolissi, mi aiuta davvero a sistemare i miei pensieri in modo rapido e conciso e mi consente persino di rifattorizzare meglio (più avanti). Inoltre, non ho mai dovuto fissare il mio codice per capire cosa ha fatto in seguito, visto che i commenti ci sono.

Inoltre, se si commenta in un secondo momento, è possibile fraintendere ciò che il codice fa in seguito e alterarlo.

Answer 16

Quando è fresco nella tua mente. È improbabile che tu lo comprenda meglio di subito dopo averlo scritto.

In alternativa, quando si torna al codice precedente e si ha difficoltà a capirlo, commentare per annotare ciò che è difficile da capire. Non contare di ricordarlo per la prossima volta; non funziona bene per me.

Detto questo, documenta perché, non come. Se devi documentare come, stai facendo delle cose complicate (nel qual caso devi documentare perché sei) o devi imparare a scrivere codice più leggibile.

Answer 17

aggiungo commenti dopo il codice è pronto e tutti i test passano, ma prima di inviare il codice. Non aggiungo i commenti prima della codifica, solo perché di solito rifatto il codice un numero di volte nel processo di scrittura, e la mia memoria è abbastanza buona da ricordare cosa sta facendo il codice quando ci sto lavorando. Quindi, documentare il codice prima che il cambiamento sia pronto è uno spreco. Inoltre, può essere visto come una specie di ottimizzazione prematura.

Quindi, dopo aver inviato il codice, aggiungo i commenti solo se qualcuno non riesce a capire cosa sta succedendo e mi sta chiedendo. (Qualcuno - incluso me stesso).

Answer 18

Tendo a scrivere commenti di classe prima di scrivere il codice e commenti di metodo subito dopo aver determinato i parametri e scritto lo scheletro del metodo. Questi vengono aggiornati man mano che evolve il design. Cerco di scegliere nomi di variabili molto chiari e di semplificare il codice per ridurre il numero di commenti a livello di istruzione necessari. Di solito scrivo commenti a livello di istruzione subito dopo aver codificato ciascun corpo del metodo, ma a volte devo prima elaborare un algoritmo nei commenti.

La cosa fondamentale è commentare quando le cose sono fresche nella vostra mente. Passando del tempo a spiegare il tuo codice agli altri, troverai anche più bug e aree in cui il codice necessita di refactoring.

Answer 19

Questo mi ha fatto pensare che, se avessi commentato il codice mentre lo scrivevo, i miei commenti potrebbero non aver aiutato un secondo "io" a decifrare il codice.

D'altra parte, potrebbero aver aiutato.

I commenti che sono stati scritti in passato sono spesso più utili ora rispetto ai commenti che non sono stati ancora scritti.

Se si dovesse deliberatamente ritardare la scrittura di commenti, si potrebbe cadere preda di "le mieux est l'ennemi du bien".

Answer 20

È stata la mia esperienza che è meglio commentare sempre il codice, anche quando il metodo ei nomi delle variabili sono autoesplicativi. È molto più facile tornare a un pezzo di codice dopo 2 anni e capirlo quando ci sono commenti. I commenti rendono il codice molto più gestibile.