Il codice commentato è davvero sempre male? [duplicare]

50

Praticamente ogni testo sulla qualità del codice che ho letto concorda sul fatto che il codice commentato è una cosa negativa. Il solito esempio è che qualcuno ha cambiato una riga di codice e ha lasciato la vecchia linea come commento, apparentemente per confondere le persone che leggono il codice in seguito. Certo, è una brutta cosa.

Ma spesso mi ritrovo a lasciare il codice commentato in un'altra situazione: scrivo un algoritmo di elaborazione della geometria o dell'immagine computazionale. Per comprendere questo tipo di codice e trovare potenziali bug in esso, è spesso molto utile visualizzare risultati intermedi (ad esempio disegnare una serie di punti sullo schermo o salvare un file bitmap). Guardare questi valori nel debugger di solito significa guardare un muro di numeri (coordinate, valori di pixel grezzi). Non molto utile. Scrivere un visualizzatore debugger ogni volta sarebbe eccessivo. Non voglio lasciare il codice di visualizzazione nel prodotto finale (danneggia le prestazioni e in genere confonde solo l'utente finale), ma non voglio perderlo neanche io. In C ++, posso usare #ifdef per compilare condizionatamente quel codice, ma non vedo molta differenza tra questo:

/* // Debug Visualization: draw set of found interest points
for (int i=0; i<count; i++)
    DrawBox(pts[i].X, pts[i].Y, 5,5);
*/

e questo:

#ifdef DEBUG_VISUALIZATION_DRAW_INTEREST_POINTS
for (int i=0; i<count; i++)
    DrawBox(pts[i].X, pts[i].Y, 5,5);
#endif

Quindi, il più delle volte, lascio semplicemente il codice di visualizzazione commentato, con un commento che dice cosa viene visualizzato. Quando leggo il codice un anno dopo, di solito sono felice di poter semplicemente decommentare il codice di visualizzazione e letteralmente "vedere cosa sta succedendo".

Dovrei stare male a riguardo? Perché? C'è una soluzione superiore?

Aggiornamento : S. Lott chiede in un commento

Are you somehow "over-generalizing" all commented code to include debugging as well as senseless, obsolete code? Why are you making that overly-generalized conclusion?

Recentemente ho letto "Codice pulito" di Robert Martins, che dice:

Few practices are as odious as commenting-out code. Don't do this!.

Ho esaminato di nuovo il paragrafo nel libro (pagina 68), non c'è alcuna qualifica, nessuna distinzione fatta tra diversi motivi per commentare il codice. Quindi mi sono chiesto se questa regola è troppo generalizzata (o se ho frainteso il libro) o se quello che faccio è una cattiva pratica, per qualche motivo non lo sapevo.

    
posta nikie 08.02.2011 - 10:37
fonte

13 risposte

57

Il vantaggio di # ifdef rispetto a commentarlo è che (su progetti di grandi dimensioni) è possibile avere le definizioni elencate in un file make o config e quindi non è necessario eseguire manualmente un commento, costruire, e poi commentarli di nuovo se è in molti posti. Lo svantaggio di questo è che cambiare DEFINE del progetto significa in genere ricostruire tutto, non solo i file modificati.

Però ... penso che il "codice commentato sia una cosa cattiva" si riferisca davvero a codice morto che le persone non volevano cancellare per qualsiasi motivo (paura di buttare via qualcosa hai passato del tempo forse?). Non si tratta veramente della situazione che stai cercando.

    
risposta data 08.02.2011 - 10:51
fonte
24

Se è commentato, potrebbe marcire: quando improvvisamente decidi di averne bisogno, ti rendi conto che non è più compilato, o che deve essere riscritto per adattarlo ad altre cose che sono cambiate nel frattempo.

Se lasci il codice, ma in modo tale che il compilatore possa ottimizzarlo via se non necessario, allora puoi trarre vantaggio dal mantenere il codice e non dover soffrire la dimensione binaria aggiunta o le prestazioni di runtime.

Ad esempio, in C, questo è a rischio di putrefazione:

/*
doSomeDebugStuff();
*/

E così è questo:

#if 0
doSomeDebugStuff();
#endif

Ma questo è positivo, dal momento che è sempre controllato dal compilatore, ma probabilmente sarà ottimizzato via:

if (0)
{
  doSomeDebugStuff();
}

Modifica: come altri sottolineano, l'utilizzo di un simbolo significativo anziché 0 per il test è ancora migliore.

    
risposta data 08.02.2011 - 11:46
fonte
14

Penso che sia necessario fare una distinzione tra codice commentato che è obsoleto e codice che viene utilizzato solo in una build di debug (o un'altra build "speciale", compilata in modo condizionale). Quest'ultima è una pratica comune e non c'è niente di sbagliato in essa.

Il primo non dovrebbe essere presente in una base di origine, in quanto il sistema di controllo della versione tiene traccia delle cose obsolete, nel caso dovessi voler tornare indietro.

    
risposta data 08.02.2011 - 10:44
fonte
13
// The problem with commented out code is that it can hide what you're actually
// trying to say in a wall of text.  Syntax highlighting may help, but you're 
// still left with this huge ginormous wall of text in front of you, searching
// through it for what the actual answer is. You'd think that mentally it'd be 
// really easy to disregard the comments, but in actual usage, it's a lot harder
// than a one word answer that can tell you what you're looking for. It's tough.
/* Sometimes they'll even through you off with different comments. */ Yes.
// It's really tough to deal with people that don't like to use source control, 
// that would rather comment lines and lines of code instead of deleting the 
// code and checking in revision.  Cue irrelevant paragraph about the reason why 
// I wrote this instead of just deleting the entire block and replacing it 
// with my intention. Maybe I was hedging my bets? Cue misspelled wrod.  
    
risposta data 08.02.2011 - 14:27
fonte
10

Quasi non c'è "sempre" nella codifica :) Se conosci abbastanza le ragioni dietro a una linea guida e hai davvero un buon motivo per romperla, fallo.

Ad esempio commento il codice quando eseguo "kamikaze-refactoring" e ho bisogno di un promemoria visivo per aggiungere le cose o ricordare come funzionava il vecchio codice per un po '. È cruciale in casi come questo che cancellerai i commenti più tardi, altrimenti faranno semplicemente confusione nel codice.

    
risposta data 08.02.2011 - 12:00
fonte
7

A volte inserisci il codice nei tuoi commenti per mostrare come utilizzare una classe - questo è molto diverso dal codice di commento che è stato utilizzato per eseguire.

    
risposta data 08.02.2011 - 13:59
fonte
3

Faccio molte revisioni del codice e trovo che non ci sia una vera scusa per il codice commentato indipendentemente dalla ragione. Se si utilizza il codice commentato per scopi di debug, è possibile creare un meccanismo di tracciamento disabilitato in modalità di rilascio o con livelli di traccia (sempre utile per essere in grado di tracciare in una versione di rilascio) o semplicemente utilizzare un debugger.

Il codice commentato è sbagliato perché quando altre persone leggono il codice - specialmente quando sei stressato a cercare di correggere un bug quando l'autore originale è in vacanza - è che è molto difficile leggere il codice, specialmente se l'errore è da una posizione errata // all'inizio della linea ... anche usando / * potresti commentare per errore qualcosa che avrebbe dovuto essere lì dentro o no.

Per mantenere il tuo codice pulito e più leggibile, rimuovi il codice commentato, i suoi programmi già difficili da leggere così com'è senza dover leggere codice che potrebbe essere o non essere significativo.

    
risposta data 08.02.2011 - 13:24
fonte
2

Sì, lo è.

Anche se hai il codice di debug che non vuoi nella tua versione di produzione, non dovresti commentare. Usare #ifdef è meglio, perché in questo modo è possibile attivare e disattivare il debug facilmente con una macro #define o con una configurazione di compilazione separata. Questo sicuramente ha bisogno di andare nel codice e commentare / decommentare manualmente ogni blocco del codice di debug.

E se hai bisogno di flessibilità per attivare alcuni blocchi di debug ma non altri, devi raggruppare i blocchi di debug in "livelli di debug".

Una soluzione migliore sarebbe quella di non utilizzare affatto il pre-processore e di utilizzare le funzionalità del linguaggio nativo, come le costanti e le istruzioni if. Quindi invece di

#define DEBUG0
#ifdef DEBUG0
  // debugging code
#endif

puoi avere

const bool DEBUG0 = true;
if(DEBUG0)
{
  // debugging code
}

Il vantaggio di fare ciò, rispetto all'uso del pre-processore, è che il codice di debug sarà sempre controllato dal compilatore. Questo diminuisce la probabilità che marcisca, quando cambi il codice attorno ad esso.

Non subirai alcun colpo a livello di prestazioni se rendi falso il flag booleano, perché i compilatori moderni ottimizzano il codice irraggiungibile. Nel peggiore dei casi, potresti ricevere un avvertimento sul compilatore.

    
risposta data 08.02.2011 - 18:32
fonte
1

Non penso che quello che stai facendo sia fuori e fuori male ma penso che almeno dovresti avere alcuni commenti con esso per spiegare cosa sta facendo, perché, come e come quando usarlo.

Personalmente normalmente inserisco questo genere di cose in una sorta di IF DebugMode = TRUE tipo di sforzo attorno al codice in questione e lo imposto come parametro da linea di comando / avvio. Per me questo rende più facile vedere che è per questo che il codice è lì e come impostarlo anche se nella tua istanza ci potrebbero essere problemi di prestazioni anche con quel piccolo confronto che desideri evitare.

Quindi probabilmente vedrei quello che stai facendo come un male necessario piuttosto che fuori e fuori sbagliato. Se riesci a trovare in qualche modo per semplificare, allora ovviamente lo fai, ma non vorrei battermi su di esso.

    
risposta data 08.02.2011 - 10:47
fonte
0

Penso che uno dei motivi per cui il codice commentato sia considerato un odore di codice è che indica che il programmatore che l'ha messo lì non capisce il loro controllo del codice sorgente o che non ne sta usando nessuno. Ognuna delle quali getta ulteriori dubbi su molte altre cose che stanno facendo pure.

Se hai una ragione legittima per e lasci una spiegazione sul motivo per cui è un motivo legittimo in cui può essere trovato che stai probabilmente andando bene. La maggior parte delle cose che sono generalmente considerate cattive notizie possono anche essere uno strumento utile nelle mani giuste. Il problema è che quelle mani sono più rare di quelle che pensano di averle.

    
risposta data 08.02.2011 - 11:12
fonte
0

Aiuta a fornire una cronologia di come funzionavano le menti dei programmatori in quel momento. Ma in questi giorni di onnipresente controllo del codice sorgente non c'è motivo di lasciarlo in un ultimo taglio - le versioni precedenti conterranno il vecchio codice se dovessi aver bisogno di farvi riferimento.

    
risposta data 08.02.2011 - 13:35
fonte
0

Non penso che qui ci siano assoluti. A volte lascio il codice commentato quando è solo un piccolo frammento, specialmente se c'è una ragionevole possibilità che lo annulli di nuovo presto. In pratica, lascio quei frammenti fino a quando non interrompono la leggibilità del codice reale, e finché non si moltiplicano ovunque.

Ciò che rifiuto assolutamente sono i metodi completi di codice commentato. Sì, ho visto quelli precedenti: WTF. Possono riposare nel paradiso della revisione sorgente; -)

    
risposta data 08.02.2011 - 14:46
fonte
-1

Utilizza il commento se il tuo programma verrà modificato da altre persone o modifichi il lavoro di altre persone. Non vuoi che altre persone cancellino il tuo codice e in seguito ha scoperto che il tuo codice era migliore. Inoltre, se invii un programma modificato da te, che è stato scritto da altri, e quindi il programma fallisce, è meglio che tu abbia commentato il codice originale dal tuo collega in modo che tu possa annullare la modifica. Sto dicendo la situazione quando la compagnia non usa un sistema di controllo della versione.

Commenta anche il tuo codice se desideri fare riferimento più tardi al tuo codice, ad esempio stai provando un approccio diverso per lo stesso obiettivo.

Il commento non influisce sulle prestazioni del linguaggio compilato o del linguaggio basato su macchine virtuali.

Se un commento trovato è davvero fastidioso, può utilizzare un IDE migliore con funzione per nascondere alcuni commenti selezionati.

    
risposta data 08.02.2011 - 10:51
fonte

Leggi altre domande sui tag