it-swarm.it

Il codice commentato è davvero sempre negativo?

Praticamente ogni testo sulla qualità del codice che ho letto concorda sul fatto che commentare il codice è una cosa negativa. Il solito esempio è che qualcuno ha cambiato una riga di codice e lasciato lì la vecchia riga come commento, apparentemente per confondere le persone che hanno letto 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 di immagini o geometria computazionale. Per comprendere questo tipo di codice e trovare potenziali bug in esso, è spesso molto utile visualizzare risultati intermedi (ad es. 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 di debugger ogni volta sarebbe eccessivo. Non voglio lasciare il codice di visualizzazione nel prodotto finale (danneggia le prestazioni e di solito confonde l'utente finale), ma non voglio nemmeno perderlo. In C++, posso usare #ifdef per compilare condizionalmente 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 commentato il codice di visualizzazione, con un commento che dice ciò che 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 sentirmi male al riguardo? Perché? C'è una soluzione superiore?

Aggiornamento: S. Lott chiede in un commento

Stai in qualche modo "over-generalizzando" tutto il codice commentato per includere il debug e il codice obsoleto senza senso? Perché stai facendo una conclusione troppo generalizzata?

Di recente ho letto "Clean Code" di Robert Martins, che dice:

Poche pratiche sono odiose come commentare il codice. Non farlo !.

Ho guardato di nuovo il paragrafo nel libro (p. 68), non esiste alcuna qualifica, nessuna distinzione fatta tra diversi motivi per commentare il codice. Quindi mi chiedevo se questa regola fosse troppo generalizzante (o se avessi frainteso il libro) o se quello che faccio fosse una cattiva pratica, per qualche motivo non lo sapevo.

53
nikie

Il vantaggio di # ifdef invece di commentarlo, è che (su progetti di grandi dimensioni) puoi avere le definizioni elencate in un file make o config - e quindi non devi andare manualmente un commento, compilare e quindi ri -commentarli se sono in molti posti. L'aspetto negativo di questo è che cambiare i DEFINE del progetto di solito significa ricostruire il tutto, non solo cambiare i file.

Anche se ... penso che il "codice commentato sia una cosa negativa" si riferisce davvero a codice morto che le persone non volevano cancellare per nessun motivo (paura di buttare via qualcosa che hanno speso tempo forse?). Non si tratta davvero della situazione che hai per te.

58
TZHX

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

Se lasci il codice dentro, ma in modo tale che il compilatore possa ottimizzarlo via se non necessario, allora beneficerai di mantenere aggiornato il codice e non dovendo subire il binario aggiunto dimensioni o prestazioni di runtime.

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

/*
doSomeDebugStuff();
*/

E così è questo:

#if 0
doSomeDebugStuff();
#endif

Ma questo è buono, dal momento che viene sempre verificato la validità dal compilatore, ma probabilmente sarà ottimizzato:

if (0)
{
  doSomeDebugStuff();
}

Modifica: come altri sottolineano, usando un simbolo significativo anziché 0 per il test è ancora meglio.

25
Graham Borland
// 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.  
18
George Stocker

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

Il primo non dovrebbe essere presente in una base di origine, poiché il sistema di controllo della versione tiene traccia delle cose obsolete, nel caso in cui si desideri ripristinarle.

15
Alex Budovski

Non c'è quasi "sempre" nella codifica :) Se conosci abbastanza i motivi alla base di una linea guida e hai delle ottime ragioni per romperla, allora fallo.

Ad esempio, commento il codice quando eseguo il "refactoring kamikaze" e ho bisogno di un promemoria visivo per aggiungere elementi o ricordare come il vecchio codice ha funzionato per un po '. È fondamentale in casi come questo che eliminerai i commenti in seguito, anche se altrimenti ingombreranno semplicemente il tuo codice.

11
Homde

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

8
Ian

Faccio molte revisioni del codice e trovo che non ci siano scuse reali per il codice commentato indipendentemente dal motivo. Se si utilizza il codice commentato per scopi di debug, è possibile creare un meccanismo di traccia che è disabilitato in modalità di rilascio o ha livelli di traccia (sempre buono per essere in grado di tracciare in una versione di rilascio) oppure è possibile semplicemente utilizzare un debugger.

Il codice commentato è negativo perché quando altre persone leggono il codice, specialmente quando sei stressato nel tentativo di correggere un bug quando l'autore originale è in vacanza, è molto confuso leggere il codice, soprattutto se l'errore proviene da un errore posto // all'inizio della riga ... anche usando/* potresti accidentalmente commentare qualcosa che avrebbe dovuto essere lì dentro o no.

Per mantenere il codice pulito e più leggibile, rimuovere il codice commentato, è già difficile leggere i programmi in quanto è senza dover leggere codice che può essere o non essere significativo.

3
AndersK

Sì.

Anche se hai un codice di debug che non desideri nella versione di produzione, non dovresti commentarlo. Utilizzando #ifdef è meglio, perché puoi attivare e disattivare facilmente il debug con un #define macro o con una configurazione di build separata. Questo sicuramente batte dover andare nel codice e commentare/decommentare manualmente ogni blocco del codice di debug.

E se è necessario disporre di flessibilità per attivare alcuni blocchi di debug ma non altri, è necessario raggruppare i blocchi di debug in "livelli di debug".

Una soluzione migliore sarebbe quella di non utilizzare affatto il pre-processore e di utilizzare funzionalità in lingua nativa, come costanti e 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 questo, rispetto all'uso del pre-processore, è che il compilatore controlla sempre il codice di debug. Ciò riduce la probabilità che marcisca, quando si modifica il codice attorno ad esso.

Non risentiresti di alcun calo delle prestazioni se rendi falsa la bandiera booleana, perché i compilatori moderni ottimizzano il codice irraggiungibile. Nel peggiore dei casi, potresti ricevere un avviso del compilatore al riguardo.

2
Dima

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

Personalmente normalmente metterei questo genere di cose in una sorta di IF DebugMode = TRUE tipo sforzo attorno al codice in questione e lo imposto come parametro da riga di comando/avvio. Per me ciò rende più semplice capire che è per questo che esiste il codice e come impostarlo, anche se nella tua istanza potrebbero esserci 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. Se riesci a trovare un modo per ottimizzarlo, ovviamente fallo, ma non mi batterei.

1
Jon Hopkins

Penso che uno dei motivi che hanno commentato il codice sia considerato un odore di codice è che indica che il programmatore che lo ha inserito non capisce il loro controllo del codice sorgente o che non ne sta usando. Ognuno dei quali getta ulteriori dubbi anche su molte altre cose che stanno facendo.

Se hai un motivo legittimo e lasci una spiegazione del perché è un motivo legittimo dove si può trovare che probabilmente stai andando bene. Molte cose che sono generalmente considerate cattive notizie possono anche essere uno strumento utile nelle mani giuste. Il problema è che quelle mani sono più rare delle persone che pensano di averle.

0
glenatron

Aiuta a fornire una storia di come le menti dei programmatori stessero lavorando in quel momento. Ma in questi giorni di onnipresente controllo del codice sorgente non c'è motivo di lasciarlo in un taglio finale: le versioni precedenti conterranno il codice precedente nel caso in cui dovessi mai fare riferimento ad esso.

0
5arx

Non penso che ci siano assoluti qui. A volte lascio il codice commentato quando è solo un piccolo frammento, soprattutto se c'è una ragionevole possibilità che lo rimuoverò presto. Fondamentalmente lascio quei frammenti fintanto che non interrompono la leggibilità del codice reale e fintanto che non si moltiplicano ovunque.

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

0
Andres F.