"I commenti sono un odore di codice" [chiuso]

Un mio collega crede che qualsiasi uso di commenti in codice (cioè, non metodo javadoc o commenti di classe) sia un odore di codice . Cosa ne pensi?

Solo se il commento descrive cosa sta facendo il codice.

Se volessi sapere cosa stava succedendo in un metodo o in un blocco, avrei letto il codice. Spero comunque che tutti gli sviluppatori che lavorano su un determinato progetto abbiano almeno abbastanza familiarità con il linguaggio di sviluppo per leggere ciò che è scritto e capire cosa sta facendo.

In alcuni casi di ottimizzazione estrema, potresti utilizzare tecniche che rendono difficile per qualcuno seguire ciò che sta facendo il tuo codice. In questi casi, i commenti possono e devono essere utilizzati non solo per spiegare perché si dispone di tali ottimizzazioni, ma cosa sta facendo il codice. Una buona regola empirica sarebbe quella di avere qualcun altro (o più altre persone) a conoscenza del linguaggio di implementazione e del progetto guardare il tuo codice - se non riescono a capire sia il perché che il come, allora dovresti commentare sia il perché che il il come.

Tuttavia, ciò che non è chiaro nel codice è il motivo per cui hai fatto qualcosa. Se adotti un approccio che potrebbe non essere ovvio per gli altri, dovresti avere un commento che spieghi perché hai preso le decisioni che hai preso. Sospetto che potresti anche non capire che è necessario un commento fino a dopo qualcosa come una recensione del codice, in cui le persone vogliono sapere perché hai fatto X invece di Y: puoi catturare la tua risposta nel codice per tutti gli altri che lo guardano nel futuro.

La cosa più importante, tuttavia, è cambiare i tuoi commenti quando cambi il tuo codice. Se cambi un algoritmo, assicurati di aggiornare i commenti con il motivo per cui hai scelto l'algoritmo X su Y. I commenti non aggiornati hanno un odore di codice ancora maggiore.

Questo è particolarmente irritante da sentire al momento, ho trascorso un po 'di tempo questo fine settimana a guardare un codice molto ben definito, molto pulito e non commentato che implementava un algoritmo di ricerca (uno che non è effettivamente pubblicato). Lo conosco di alto livello, il ragazzo seduto accanto a me era l'inventore e il codice è stato scritto qualche anno fa da qualcun altro. Potremmo a malapena seguirlo.

Il tuo collega non ha abbastanza esperienza, ovviamente.

I commenti dovrebbero spiegare perché, non come.

Howi commenti di tipo vengono generalmente gestiti meglio con il refactoring. Personalmente, di solito evito i commenti a favore del refactoring.

Prima:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

dopo:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

Dichiaro eretico il tuo collega! Dove sono i miei stivali che bruciano l'eretico?

I commenti ossessivi sono un male e un mal di testa da manutenzione, e i commenti non sostituiscono metodi ben noti, classi, variabili, ecc. Ma a volte mettere il motivo per cui qualcosa è così può essere immensamente prezioso per il povero idiota che deve mantenere il codice in sei mesi, in particolare quando quel povero idiota finisce per essere te.

Alcuni commenti reali dal codice su cui sto lavorando:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

Idealmente, il codice dovrebbe essere così ben codificato che dovrebbe essere autoesplicativo. Nel mondo reale, sappiamo che anche a volte un codice di qualità molto elevata necessita di commenti.

Quello che dovresti assolutamente evitare è la "ridondanza di commenti-codice" (commenti che non aggiungono nulla al codice):

i++; // Increment i by 1

Quindi, se esiste una buona progettazione (e mantenuta / allineata) del codice e documentazione, commentare è ancora meno utile.

Ma in alcune circostanze i commenti possono essere un buon aiuto nella leggibilità del codice:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Non dimenticare che devi mantenere e sincronizzare anche i commenti ... commenti obsoleti o sbagliati possono essere un dolore terribile! E, come regola generale, commentare troppo può essere un sintomo di cattiva programmazione.

Definire categoricamente un metodo o un processo come "odore di codice" è un "odore di zelo". Il termine sta diventando il nuovo "considerato dannoso".

Ricorda che tutte queste cose dovrebbero essere linee guida.

Molte delle altre risposte danno buoni consigli su quando i commenti sono giustificati.

Personalmente utilizzo pochissimi commenti. Spiega lo scopo di processi non ovvi e lascia l'occasionale minaccia di morte a chiunque stia prendendo in considerazione la possibilità di modificare da solo le cose che richiedono settimane di messa a punto.

Rifattorizzare tutto fino a quando un asilo non può capire che probabilmente non è un uso efficiente del tuo tempo e probabilmente non funzionerà come una versione più concisa.

I commenti non influiscono sul tempo di esecuzione, quindi l'unico problema negativo da considerare è la manutenzione.

In alcuni casi, nessuna quantità di buona denominazione, refactoring ecc. Può sostituire un commento. Guarda questo esempio del mondo reale (la lingua è Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Sembra strano, no? Probabilmente un errore di copia-incolla? Grida per una correzione?

Ora lo stesso con i commenti:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

Il problema principale qui è il significato del termine "odore di codice".

Molte persone (incluso te, penso) capiscono che un odore di codice sia qualcosa di simile a un errore o almeno qualcosa che deve essere risolto. Forse lo pensi come un sinonimo di "anti-pattern".

Questo non è il significato del termine!

La metafora dell'odore del codice proviene da Wards Wiki e sottolineano:

Si noti che CodeSmell è un suggerimento che qualcosa potrebbe essere sbagliato, non una certezza. Un idioma perfettamente buono può essere considerato un CodeSmell perché è spesso usato in modo improprio o perché esiste un'alternativa più semplice che funziona nella maggior parte dei casi. Chiamare qualcosa come CodeSmell non è un attacco; è semplicemente un segno che uno sguardo più attento è garantito.

Quindi cosa significa che i commenti sono un odore di codice: significa che quando vedi un commento, dovresti metterti in pausa e pensare: "Hmmm, sento un indizio che qualcosa potrebbe essere migliorato". Forse puoi rinominare una variabile, eseguire il "metodo extract" -refactoring - o forse il commento è in realtà la soluzione migliore.

Questo è ciò che significa che i commenti sono odori di codice.

EDIT: Ho appena inciampato in questi due articoli, il che spiega meglio di me:

• Scuse nel codice
• Per avere bisogno di commenti

Penso che la regola sia abbastanza semplice: immagina un completo sconosciuto che vede il tuo codice. Probabilmente sarai estraneo al tuo codice tra 5 anni. Cerca di ridurre al minimo lo sforzo mentale per comprendere il tuo codice per questo sconosciuto.

Una buona idea per avere i commenti giusti è iniziare con la scrittura di commenti.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Ciò ti consente di estrarre facilmente metodi per sbarazzarti dei commenti,
lascia che il codice dica queste cose ! Guarda come questo viene riscritto (taglia / incolla) in un modo molto bello:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Per cose che non possono essere separate, non estrarre i metodi e digitare il codice sotto i commenti.

Questo è quello che vedo come un modo utile per ridurre al minimo i commenti, è davvero inutile commentare ogni riga ... Documentare una sola riga se si tratta di un'inizializzazione di valore magico o dove ha senso.

Se i parametri sono usati troppo, allora dovrebbero essere membri privati ​​nella tua classe.

Penso che la risposta sia la solita "Dipende". Commentare il codice solo per commentare il codice è un odore. Commentare il codice perché stai usando un oscuro algoritmo che è un ordine di grandezza più veloce salva il programmatore di manutenzione (di solito io 6 mesi dopo averlo scritto) mezza giornata di frugare nel codice per determinare cosa sta facendo.

// Dear me in the future. Please, resolve this problem.

o

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

I commenti sul codice non sono sicuramente un "odore di codice". Questa convinzione deriva in genere dal fatto che i commenti possono diventare obsoleti (non aggiornati) e possono essere difficili da mantenere. Tuttavia, avere buoni commenti che spiegano perché il codice sta facendo qualcosa in un certo modo può (e di solito è) importante per la manutenzione.

I buoni commenti rendono più facile capire cosa sta facendo il codice e, cosa più importante, perché lo sta facendo in un modo particolare. I commenti devono essere letti dai programmatori e devono essere chiari e precisi. Un commento che è difficile da capire o errato non è molto meglio di non aver avuto alcun commento.

L'aggiunta di commenti chiari e precisi al codice significa che non è necessario fare affidamento sulla memoria per comprendere il "cosa" e il "perché" di una sezione di codice. Questo è molto importante quando guardi quel codice in seguito, o qualcun altro deve guardare il tuo codice. Poiché i commenti diventano parte del contenuto testuale del tuo codice, dovrebbero seguire buoni principi di scrittura oltre a essere scritti chiaramente.

Per scrivere un buon commento, dovresti fare del tuo meglio per documentare lo scopo del codice (il perché, non come) e indicare il ragionamento e la logica alla base del codice nel modo più chiaro possibile. Idealmente, i commenti dovrebbero essere scritti contemporaneamente alla scrittura del codice. Se aspetti, probabilmente non tornerai indietro e li aggiungerai.

Sams Teach Yourself Visual C # 2010 in 24 Hours , pp 348-349.

Se il codice è stato scritto in un modo particolare per evitare un problema presente in una libreria (sia una libreria di terze parti, sia una libreria fornita con il compilatore), ha senso commentarlo.
Ha anche senso commentare il codice che deve essere modificato nelle versioni future, o quando si utilizza una nuova versione di una libreria o, ad esempio, quando si passa da PHP4 a PHP5.

Anche il libro più ben scritto ha ancora probabilmente un'introduzione e titoli di capitolo. I commenti in un codice ben documentato sono ancora utili per descrivere concetti di alto livello e spiegare come è organizzato il codice.

Di menzione d'onore è l'anti-pattern:

La mia impressione è che a volte i preamplificatori di licenza FLOSS vengano spesso utilizzati al posto della documentazione dei file. GPL / BSDL crea un bel testo di riempimento e dopo raramente vedi altri blocchi di commenti.

Non sono d'accordo con l'idea che scrivere commenti per spiegare il codice sia negativo. Questo ignora completamente il fatto che il codice abbia dei bug. Potrebbe essere chiaro ciò che il codice fa , senza commenti. È meno probabile che sia chiaro cosa dovrebbe fare il codice . Senza commenti come fai a sapere se i risultati sono sbagliati o se vengono utilizzati in modo errato?

I commenti dovrebbero spiegare l' intento del codice, in modo che se si verifica un errore, qualcuno che legge i commenti + codice ha la possibilità di trovarlo.

In genere mi ritrovo a scrivere commenti incorporati prima di scrivere il codice. In questo modo è chiaro cosa sto provando a scrivere il codice da fare e riduce la perdita in un algoritmo senza sapere davvero cosa stai cercando di fare.

I commenti inseriti perché qualcuno pensa che sia giusto avere 700 righe in un metodo sono un odore.

I commenti che ci sono perché sai che se non aggiungi un commento, qualcuno farà di nuovo lo stesso errore sono ancora un odore.

Commenti inseriti perché alcuni strumenti di analisi del codice richiedono che siano anche un odore.

Anche le persone che non inseriranno mai un commento o scriveranno neanche un piccolo aiuto per altri sviluppatori sono un odore. Sono sorpreso di quante persone non scriveranno cose, ma poi si gireranno e riconosceranno di non ricordare cosa hanno fatto 3 mesi fa. Non mi piace scrivere documenti, ma mi piace dover dire alle persone la stessa cosa ancora e ancora ancora di meno.

Risponderò con una mia domanda. Riesci a trovare il bug nel codice non commentato di seguito?

tl; dr: la prossima persona a mantenere il tuo codice potrebbe non essere così divina come te.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

Devi mantenere un equilibrio tra codice e commenti ... Di solito provo ad aggiungere alcuni commenti che riprendono un blocco di codice. Non perché non sarò in grado di capire il codice (bene, anche quello), ma perché posso leggere più velocemente il mio codice e individuare sezioni specifiche in cui stanno accadendo le cose importanti.

Ad ogni modo, i miei criteri personali sono "in caso di dubbi, commentare". Preferisco avere una linea ridondante rispetto a una linea completamente enigmatica che non riuscirò a capire. Posso sempre rimuovere i commenti su una revisione del codice, dopo un po '(e di solito lo faccio)

Inoltre, i commenti sono molto utili aggiungendo "avvertenze" come "Attenzione! Se il formato dell'input non è ASCII, questo codice dovrà cambiare!"

Leggendo questo mi viene in mente qualcosa che ho letto per la prima volta (da un elenco più lungo, conservato facendo delle fotocopie) alcuni decenni fa:

I veri programmatori non scrivono commenti: se fosse difficile da scrivere, dovrebbe essere difficile da leggere

Un odore piuttosto vecchio sembra.

Penso che commentare il codice abbia un inizio molto brutto nella vita. Non so di questi tempi, ma quando mi è stato insegnato per la prima volta a programmare a scuola, ho ricevuto incarichi della natura di "Scrivi un programma che stampa i numeri da uno a dieci su righe separate. Assicurati di commentare il tuo codice." Saresti segnato se non hai aggiunto commenti perché commentare il tuo codice è una buona cosa.

Ma cosa c'è da dire su un processo così banale? Quindi finisci per scrivere il classico

i++; // add one to the "i" counter.

solo per ottenere un voto decente e, se hai qualche nous, formando immediatamente un'opinione molto bassa dei commenti sul codice.

Commentare il codice non è una BUONA COSA. È ALCUNA COSA NECESSARIA, e Thomas Owens nella risposta in alto fornisce una spiegazione eccellente delle situazioni in cui è necessario. Tuttavia, queste situazioni raramente insorgono in compiti tipo compiti a casa.

In molti modi, l'aggiunta di un commento dovrebbe essere considerata una scelta di ultima istanza, quando ciò che deve essere detto non può essere detto chiaramente nelle parti attive del linguaggio di programmazione. Sebbene la denominazione degli oggetti possa diventare viziata, vari meccanismi di mancanza di feedback umani e informatici rendono facile dimenticare di conservare i commenti e di conseguenza i commenti diventano viziati molto più rapidamente del codice attivo. Per tale motivo, laddove sia possibile una scelta, la modifica del codice per renderlo più chiaro dovrebbe essere sempre preferita all'annotazione di codice non chiaro con commenti.

Ovviamente i commenti sono un odore di codice ...

ogni programmatore sa che alla fine tutti diventiamo pazzi a causa della quantità di lavoro, debugging o semplice follia in cui ci imbattiamo.

"Fai questo!" dice il project manager.

Tu rispondi "Non si può fare".

Dicono: "Quindi troveremo qualcun altro per farlo".

Dici "OK, beh forse si può fare".

E poi trascorri il prossimo numero X di giorni .. settimane .. mesi .. cercando di capirlo. Durante tutto il processo, proverai e fallirai, e proverai e fallirai. Lo facciamo tutti. La vera risposta è che ci sono due tipi di programmatori, quelli che commentano e quelli che non lo fanno.

1) Quelli che lo stanno facendo stanno semplificando il proprio lavoro documentando per riferimento futuro, commentando le routine fallite che non hanno funzionato (l'odore non le sta cancellando dopo aver trovato quello che funziona), o spezzando il codice con un commento formattazione al spera renderlo un po 'più facile da leggere o capire. Seriamente, non posso biasimarli. Ma alla fine, si spezzano e poi hai questo: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Quelli che non fanno finta di essere un supereroe o vivono in una grotta . Hanno semplicemente un disprezzo spericolato per gli altri, loro stessi, e potrebbero fregarsene di meno del codice o del significato che potrebbe avere in un secondo momento.

Ora non fraintendetemi ... variabili e funzioni auto-documentanti possono evitarlo del tutto .. e credetemi, non potrete mai fare abbastanza pulizia del codice. Ma la semplice verità è che, fintanto che si mantiene backup, è possibile SEMPRE eliminare i commenti.

Direi che non usare alcuni commenti nel tuo codice è un odore di codice. Mentre sono d'accordo sul fatto che il codice dovrebbe essere auto-documentante il più possibile, si colpisce un certo punto in cui si vedrà un codice che non ha alcun senso indipendentemente da quanto bene sia scritto. Ho visto del codice nelle applicazioni aziendali in cui i commenti sono praticamente obbligatori perché:

1. Devi fare qualcosa caso per caso e non c'è una buona logica per farlo.
2. Il codice cambierà probabilmente tra un anno o due quando le leggi verranno modificate e si desidera ritrovarlo rapidamente.
3. Qualcuno ha modificato il codice in passato perché non capiva cosa stesse facendo il codice.

Inoltre, le guide di stile aziendale potrebbero dirti di fare qualcosa in un certo modo - se dicono che potresti avere commenti che descrivono quali blocchi di codice in una funzione sta facendo, quindi includi i commenti.

C'è una grande differenza fondamentale tra commenti e codice: i commenti sono un modo per le persone di comunicare idee ad altre persone, mentre il codice è principalmente pensato per il computer. Ci sono molti aspetti nel "codice" che è anche solo per l'uomo, come la denominazione e il rientro. Ma i commenti sono scritti rigorosamente per gli umani, dagli umani.

Pertanto, scrivere commenti è altrettanto difficile di qualsiasi comunicazione umana scritta! Lo scrittore dovrebbe avere una chiara idea di chi sia il pubblico e di che tipo di testo avranno bisogno. Come fai a sapere chi leggerà i tuoi commenti tra dieci, venti anni? E se la persona provenisse da una cultura completamente diversa? Ecc. Spero che tutti lo capiscano.

Anche all'interno della piccola cultura omogenea in cui vivo, è così difficile comunicare idee ad altre persone. La comunicazione umana di solito fallisce, tranne per caso.

Devo essere d'accordo con il tuo collega. Io dico sempre che se io commento il mio codice, vuol dire che sono preoccupato che io non sarò in grado di capire il mio codice in futuro. Questo è un brutto segno.

L'unica altra ragione per cui spargo dei commenti nel codice è di chiamare qualcosa che non sembra avere senso.

Questi commenti di solito assumono la forma di qualcosa del tipo:

//xxx what the heck is this doing??

o

// removed in version 2.0, but back for 2.1, now I'm taking out again

Commenti sul codice che forniscono, ove applicabile, unità di argomenti e restituzioni di funzioni, campi di struttura e persino variabili locali possono essere molto utili. Ricorda il Mars Orbiter!

Ecco la mia regola empirica:

• Scrivi il codice e archivia un breve riassunto del codice in un documento separato.
• Lasciare il codice da solo per diversi giorni per lavorare su qualcos'altro.
• Ritorna al codice. Se non riesci a capire immediatamente cosa dovrebbe fare, aggiungi il riepilogo al file di origine.

Informa il tuo collega sulla tecnica di programmazione letterata .

No, i commenti non sono un odore di codice, sono solo uno strumento che può essere abusato.

Esempi di buoni commenti:

// Penso che questo sia in cm. Sono necessarie ulteriori indagini!

// Questo è un modo intelligente di fare X

// L'elenco è garantito non vuoto qui