In quale fase dello sviluppo dovrebbero essere scritti i commenti?

Il codice dovrebbe essere auto-descrittivo, quando possibile. In altre parole, se scrivi codice chiaro, avrai bisogno di meno commenti.

I commenti dovrebbero includere:

1. Una descrizione generale della classe / metodo e cosa fa,
2. Come oggetti e metodi si relazionano tra loro, come un'architettura generale.
3. Tutto ciò che non è immediatamente evidente dalla lettura del codice, come oscure ottimizzazioni delle prestazioni.

In generale, i commenti dovrebbero essere scritti quando sono necessari, che idealmente è quando scrivi il codice che li richiede.

Evita i commenti che dicono ovvio, o riafferma ciò che è già chiaro nel codice. Più commenti hai, più commenti dovrai mantenere quando cambi il codice.

Preferirei suggerire a chiunque scrivere commenti dall'inizio dello sviluppo, poiché le ragioni e il contesto sono più freschi nella mente. Ciò ti farà risparmiare un notevole sforzo di manutenzione, dal momento che ricordare tali intenti può essere esponenzialmente difficile con il passare del tempo.

Ci sono diverse regole empiriche per commentare il codice, tengo un elenco abbreviato per l'uso pratico.

1. essere sintetico nel dire che cosa sta facendo
2. lascia il come viene fatto al codice, commentando solo le cose non ovvie o la metodologia generale (come fare riferimento a una soluzione ben conosciuta, un algoritmo o una relazione)
3. ogni volta che devi giustificare un uso non idiomatico della lingua (in genere richiedono trucchi sulle prestazioni)

Tutti questi elementi sono meglio notati da un corretto processo di peer-review.

Scrivi i commenti mentre scrivi il codice. Sono lì per il tuo beneficio, oltre al beneficio di chiunque possa leggere successivamente il codice.

Hai le cose a metà quando parli di "spiega perché questo blocco è usato", ma la fase di debug sarà troppo tardi per farlo. Se devi pensare al motivo per cui hai scritto le cose in un certo modo in questa fase successiva, allora sei già in una posizione in cui un commento scritto durante la scrittura del codice ti avrebbe risparmiato tempo e problemi.

Servono anche per aiutarti a focalizzare la mente mentre codifichi; piuttosto che correre avanti con qualcosa ti costringono a fermarti per un po ', pensa un po' di più a ciò che stai facendo ora , e può impedirti di seguire una traccia sbagliata.

Nessuno di ciò vuol dire che mentre scrivi il codice è l'ora solo che dovresti scrivere commenti. Se, durante qualsiasi fase successiva (non solo il debugging) sembra opportuno aggiungere un ulteriore commento, modificarne uno esistente o aggiungerne uno nuovo in cui non ce n'era uno prima (o addirittura rimuoverne uno che ora sembra non necessario), quindi fatelo anche.

Idealmente, i commenti dovrebbero essere scritti contemporaneamente al codice.

Nel mondo reale, quei commenti non sono quasi altrettanto spesso richiesti, quindi se incappi in un pezzo di codice che, secondo te, merita un commento aggiuntivo, non dovrebbe esserci nulla contro l'aggiunta successiva (o commentandolo se lo hai trovato durante una recensione).

Molto spesso scrivo commenti prima e invece di codice. In questo modo espongo un piano del futuro codice in termini di alto livello.

Quindi aggiungo il codice suggerito dai commenti. I commenti descrivono cosa e perché è fatto, il codice aggiunge come .

Dopo, alcuni commenti potrebbero essere cancellati, se il codice è abbastanza trasparente; alcuni (molto meno) commenti devono essere espansi.

In questo modo, raramente devo aggiungere commenti al codice esistente.

Il tuo metodo funzionerà alla grande IFF ogni parte del codice che scrivi viene completamente debugata e hai molti passaggi per commentarla. Si spera che un giorno si scriva un altro codice che funzioni bene (più o meno) al primo tentativo. Il che significa meno o meno lunghe sessioni di debug, il che significa meno o niente o commenti, se segui rigorosamente un "commento solo quando regola il debug".

Direi di scrivere i commenti mentre scrivi il codice. Se scrivi un codice che ritieni possa richiedere ulteriori spiegazioni, scrivi i commenti non appena ti rendi conto che potrebbero essere necessari !!

(e sì, sarà necessario aggiornare i tuoi commenti se il tuo codice cambia in modo tale che i commenti non siano più validi)

I commenti possono essere scritti in qualsiasi momento, i commenti DOVREBBE essere scritti quando ritieni che il codice richieda una spiegazione e tu sai che lo capisci.

Credere che il codice abbia bisogno di spiegazioni dovrebbe quasi sempre basarsi sulla tua convinzione su quanto sia facile capire lo scopo del codice - se lo scopo è chiaro, allora probabilmente non hai bisogno di una spiegazione su cosa sia facendo. Questo è in parte lo scopo del buon naming - in modo che dato un nome di una funzione e il suo input / output, capirai perché il codice è necessario e perché sta facendo tutto ciò che sta facendo.

I commenti sulla sintassi dovrebbero essere estremamente rari, praticamente limitati ai casi in cui è BOTH oscuro E possibile fraintendere che sia qualcos'altro. Se è semplicemente oscuro, fidati che lo guarderanno se ne avranno bisogno, se è semplicemente probabile che sia frainteso a + b * c , quindi scriverlo in modo che sia meno probabile che fraintenda a + (b*c) . Se d'altra parte lo scopo non è chiaro (lavorando attorno a un bug di framework / compilatore per un esempio estremo), allora hai bisogno di un commento in modo che la prossima persona possa capire perché stai facendo quello che stai facendo.

L'aggiunta di commenti durante il debug va bene, il debug ti riporta in modo naturale al codice più vecchio che potresti faticare a capire e, lottando per capire, sai che ha bisogno di commenti.

Questo potrebbe essere il motivo per cui molte persone iniziano a dare commenti sulla sintassi - non l'hanno ancora padroneggiato, e ne stanno ancora lottando un po ', e non hanno abbastanza esperienza per rendersi conto che la sintassi è qualcosa che loro imparerò e capirò dopo. Si aspettano di avere problemi a comprendere la sintassi e quindi fornire un commento.

Ma avere questa come normale modalità di funzionamento non è l'ideale, nella migliore delle ipotesi è quindi utile la seconda volta che devi eseguire il debug di quel codice. Dovresti sforzarti di anticipare dove avrai difficoltà a capire il codice e scrivere i commenti spiegandoli come è scritto. Non aspettarti di farlo bene tutto il tempo, o anche la maggior parte del tempo all'inizio. Cerca di fare meglio.