Il codice commentato può essere una preziosa documentazione?

Ho scritto il seguente codice:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

C'è una linea commentata qui. Ma penso che renda il codice più chiaro, rendendo evidente quale sia la differenza tra ife else. La differenza è ancora più evidente con l'evidenziazione del colore.

Commentare un codice come questo può mai essere una buona idea?

La maggior parte delle risposte si concentra su come riformattare questo caso specifico, ma lasciatemi offrire una risposta generale al motivo per cui il codice commentato è solitamente negativo:

Innanzitutto, il codice commentato non viene compilato. Questo è ovvio, ma significa che:

1. Il codice potrebbe non funzionare nemmeno.

2. Quando le dipendenze del commento cambiano, non si romperà ovviamente.

Il codice commentato è molto "codice morto". Più a lungo rimane lì, più marcisce e fornisce sempre meno valore allo sviluppatore successivo.

In secondo luogo, lo scopo non è chiaro. Hai davvero bisogno di un commento più lungo che fornisca il contesto del perché ci sono righe commentate casualmente. Quando vedo solo una riga di codice commentata, devo cercare come è arrivato lì solo per capire perché è arrivato lì. Chi lo ha scritto? Che impegno? Qual era il messaggio / contesto di commit? Eccetera.

Considera le alternative:

• Se l'obiettivo è fornire esempi di utilizzo di una funzione / api, fornire un test unitario. I test unitari sono codice reale e si interromperanno quando non saranno più corretti.
• Se lo scopo è preservare una versione precedente del codice, utilizzare il controllo del codice sorgente. Preferirei piuttosto fare il checkout di una versione precedente, quindi attivare / disattivare i commenti in tutta la base di codice per "ripristinare" una modifica.
• Se lo scopo è mantenere una versione alternativa dello stesso codice, utilizzare il controllo del codice sorgente (di nuovo). Ecco a cosa servono i rami, dopo tutto.
• Se lo scopo è di chiarire la struttura, considerare come è possibile ristrutturare il codice per renderlo più ovvio. La maggior parte delle altre risposte sono buoni esempi di come potresti farlo.

Il problema più grande con questo codice è che hai duplicato quelle 6 righe. Una volta eliminata quella duplicazione, quel commento è inutile.

Se si crea un boutiqueDao.mergeOrPersistmetodo, è possibile riscriverlo come:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

Il codice che crea o aggiorna un determinato oggetto è comune, quindi è necessario risolverlo una volta, ad esempio creando un mergeOrPersistmetodo. Certamente non dovresti duplicare tutto il codice di assegnazione per quei due casi.

Molti ORM hanno integrato il supporto per questo in qualche modo. Ad esempio, potrebbero creare una nuova riga se idè zero e aggiornare una riga esistente se idnon è zero. La forma esatta dipende dall'ORM in questione e poiché non ho familiarità con la tecnologia che stai utilizzando, non posso aiutarti.

Se non si desidera creare un mergeOrPersistmetodo, è necessario eliminare la duplicazione in qualche altro modo, ad esempio introducendo un isNewBoutiqueflag. Potrebbe non essere carino, ma è comunque molto meglio che duplicare l'intera logica di assegnazione.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

Questa è un'idea assolutamente orribile . Non chiarisce quale sia l'intento. Lo sviluppatore ha commentato la riga per errore? Per testare qualcosa? Cosa sta succedendo?!

A parte il fatto che vedo 6 righe assolutamente uguali in entrambi i casi. Piuttosto, dovresti impedire questa duplicazione del codice. Quindi sarà più chiaro che in un caso si chiama inoltre setSelected.

No, è un'idea terribile. Sulla base di quel pezzo di codice mi vengono in mente i seguenti pensieri:

• Questa riga viene commentata perché lo sviluppatore ha eseguito il debug e ha dimenticato di ripristinare la riga al suo stato precedente
• Questa riga è commentata perché una volta faceva parte della logica aziendale, ma non è più il caso
• Questa riga è commentata perché ha causato problemi di prestazioni sulla produzione e lo sviluppatore ha voluto vedere quale impatto ha avuto su un sistema di produzione

Dopo aver visto migliaia di righe di codice commentato, ora sto facendo l'unica cosa sensata quando lo vedo: lo rimuovo immediatamente.

Non esiste alcun motivo ragionevole per archiviare il codice commentato in un repository.

Inoltre, il tuo codice utilizza molte duplicazioni. Ti suggerisco di ottimizzarlo per la leggibilità umana il prima possibile.

Vorrei solo aggiungere alla risposta di CodesInChaos, sottolineando che è possibile riformattare ulteriormente in piccoli metodi . La condivisione di funzionalità comuni per composizione evita i condizionali:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Mentre questo chiaramente non è un buon caso per il codice commentato, c'è una situazione che penso lo meriti:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

È un avvertimento per chiunque vedrà in seguito che l'ovvio miglioramento non lo è.

Modifica: sto parlando di qualcosa di piccolo. Se è grande, spieghi invece.

In questo esempio specifico, trovo il codice commentato molto ambiguo, in gran parte per i motivi indicati nella risposta di Dibkke . Altri hanno suggerito modi in cui potresti refactoring il codice per evitare anche la tentazione di farlo, tuttavia, se ciò non fosse possibile per qualche motivo (ad esempio, le linee sono simili, ma non abbastanza vicine), apprezzerei un commento come:

// Non è necessario deselezionare questa boutique, perché [WHATEVER]

Tuttavia, penso che ci siano alcune situazioni in cui lasciare (o addirittura aggiungere commenti commentati) non è riprovevole. Quando si utilizza qualcosa come MATLAB o NumPY, si può spesso scrivere codice equivalente che 1) scorre su un array, elaborando un elemento alla volta o 2) che gestisce l'intero array contemporaneamente. In alcuni casi, quest'ultimo è molto più veloce, ma anche molto più difficile da leggere. Se sostituisco del codice con il suo equivalente vettoriale, inserisco il codice originale in un commento vicino, in questo modo:

%% Il codice vettoriale qui sotto fa questo:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% ma la versione a matrice funziona circa 15 volte più veloce sull'input tipico (MK, 03/10/2013)

Ovviamente, bisogna fare attenzione che le due versioni facciano effettivamente la stessa cosa e che il commento rimanga sincronizzato con il codice attuale o venga rimosso se il codice cambia. Ovviamente, si applicano anche le solite avvertenze sull'ottimizzazione prematura ...

L'unica volta che ho visto il codice commentato che era utile era nei file di configurazione, in cui viene fornito il codice per ogni opzione, ma commentato, rendendo facile abilitare le impostazioni semplicemente rimuovendo i marcatori di commento:

## Enable support for mouse input:
# enable_mouse = true

In questo caso, il codice commentato aiuta a documentare tutte le opzioni disponibili e come usarle. È anche convenzionale utilizzare i valori predefiniti in tutto, quindi il codice documenta anche le impostazioni predefinite.

In generale, il codice è auto-documentante solo per la persona che ha scritto il codice. Se è necessaria la documentazione, scrivere la documentazione. È inaccettabile aspettarsi che uno sviluppatore nuovo di una base di codice sorgente si sieda a leggere migliaia di righe di codice per tentare di capire da alto livello ciò che sta accadendo.

In questo caso, lo scopo della riga di codice commentata è mostrare la differenza tra due istanze di codice duplicato. Invece di provare a documentare sottilmente la differenza con un commento, riscrivi il codice in modo che abbia senso. Quindi, se ritieni ancora necessario commentare il codice, scrivi un commento appropriato.

No, il codice commentato diventa stantio ed è presto peggio che inutile, spesso è dannoso, poiché cementa alcuni aspetti dell'implementazione, insieme a tutte le ipotesi attuali.

I commenti dovrebbero includere i dettagli dell'interfaccia e la funzione prevista; "funzione prevista": può includere, prima proviamo questo, poi proviamo quello, poi falliamo in questo modo.

I programmatori che ho visto tentano di lasciare delle cose nei commenti, sono semplicemente innamorati di ciò che hanno scritto, non vogliono perderlo, anche se non aggiunge nulla al prodotto finito.

Può essere in casi molto rari, ma non come l'hai fatto. Le altre risposte hanno abbastanza ben spiegato le ragioni di ciò.

Uno dei rari casi è una specifica RPM modello che utilizziamo nel mio negozio come punto di partenza per tutti i nuovi pacchetti, in gran parte per assicurarsi che non venga tralasciato nulla di importante. La maggior parte, ma non tutti i nostri pacchetti hanno un tarball contenente fonti che ha un nome standard ed è specificato con un tag:

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

Per i pacchetti senza fonti, commentiamo il tag e inseriamo un altro commento sopra di esso per mantenere il formato standard e indicare che qualcuno si è fermato e ha pensato al problema come parte del processo di sviluppo:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

Non aggiungi il codice che sai che non verrà utilizzato perché, come altri hanno spiegato, potrebbe essere scambiato per qualcosa che appartiene lì. Può. tuttavia, sii utile per aggiungere un commento che spieghi perché manca il codice che ci si potrebbe aspettare:

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

Il codice commentato non viene utilizzato dall'applicazione, quindi deve essere accompagnato da ulteriori commenti che indicano perché non viene utilizzato. Ma in quel contesto, ci sono situazioni in cui il codice commentato può essere utile.

Quello che mi viene in mente è un caso in cui risolvi un problema usando un approccio comune e accattivante, ma poi si scopre che i requisiti del tuo problema reale sono leggermente diversi da quel problema. Soprattutto se i tuoi requisiti risultano richiedere molto più codice, la tentazione per i manutentori di "ottimizzare" il codice usando il vecchio approccio sarà probabilmente forte, ma farlo riporterà solo il bug. Mantenere l'implementazione "sbagliata" nei commenti aiuterà a dissipare ciò, perché puoi usarlo per illustrare esattamente perché questo approccio è sbagliato in questa situazione.

Questa non è una situazione che posso immaginare accadere molto spesso. Di solito, dovrebbe essere sufficiente spiegare le cose senza includere un esempio di implementazione "sbagliata". Ma posso immaginare un caso in cui ciò non è abbastanza, quindi poiché la domanda è se può essere utile, sì, può. Solo non il più delle volte.

Questo non sembra buono amico.

Il codice commentato è ... non solo codice. Il codice è per l'implementazione della logica. Rendere un codice più leggibile in sé è un'arte. Come @CodesInChaos ha già suggerito che le linee di codice ripetitive non sono un'ottima implementazione della logica .

Pensi davvero che un vero programmatore preferirà la leggibilità rispetto all'implementazione logica. (a proposito abbiamo commenti e "complementi" da inserire nella nostra rappresentazione logica).

Per quanto mi riguarda, si dovrebbe scrivere un codice per il compilatore e va bene - se "capisce" quel codice. Per la leggibilità umana, i commenti sono positivi, per gli sviluppatori (a lungo termine), per le persone che riutilizzano quel codice (ad es. Tester).

Altrimenti puoi provare qualcosa di più flessibile qui, qualcosa di simile

boutique.setSite (sito) può essere sostituito con

setsiteof.boutique (sito). Esistono diversi aspetti e prospettive di OOP attraverso i quali è possibile aumentare la leggibilità.

Mentre questo codice sembra essere molto allettante all'inizio e si può pensare di aver trovato un modo per la leggibilità umana mentre anche il compilatore fa perfettamente il suo lavoro, e tutti iniziamo seguendo questa pratica porterà a un file fuzzy che diventerà meno leggibile nel tempo e più complesso in quanto si espanderà verso il basso.