it-swarm.it

"I commenti sono un odore di codice"

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

100
Fishtoaster

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 usati non solo per spiegare perché si hanno tali ottimizzazioni, ma anche cosa sta facendo il codice. Una buona regola empirica sarebbe quella di avere qualcun altro (o più altre persone) familiare con il linguaggio di implementazione e il 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 revisione 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.

167
Thomas Owens

Ciò è 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.

110
Paul Nathan

I commenti dovrebbero spiegare perché, non come.

I commenti di tipo How 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)
75
Sam Saffron

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. perché qualcosa è come 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.

32
BlairHippo

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.

29
Wizard79

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.

26
Bill

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 di codice ha origine 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.

Ecco cosa significa che i commenti sono odori di codice.

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

23
Rasmus Faber

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
23
user281377

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.

21

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 anche 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.

11
Tamara Wijsman

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.

10
Brandon
// 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.
10
Zzz

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 insegna a te stesso Visual C # 2010 in 24 ore , pp 348-349.

8
Scott Dorman

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 quando si passa da PHP4 a PHP5, ad esempio.

6
kiamlaluno

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.

6
munificent

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

La mia impressione è che a volte i preamplificatori di licenza FLOSS vengano frequentemente utilizzati in luogo della documentazione del file. GPL/BSDL crea un testo di riempimento di Nizza, dopodiché raramente vedi altri blocchi di commenti.

4
mario

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 che cosa il codice fa senza commenti. È meno probabile che sia chiaro cosa deve fare il codice supposto. Senza commenti come fai a sapere se i risultati sono sbagliati o se vengono utilizzati in modo errato?

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

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

4
Danny Tuppeny

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
3
Ant

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 mai inseriscono un commento o scrivono anche 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 alla gente sempre la stessa cosa ancora e ancora.

3
MIA

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 dubbio, commento". 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!"

2
Khelben

Penso che commentare il codice abbia un inizio molto brutto nella vita. Non conosco questi giorni, 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.

2
Alohci

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.

2
Murph

Ovviamente i commenti sono un odore di codice ...

ogni programmatore sa che alla fine tutti impazziamo 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 su si spera rende 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 caverna . 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 autodocumentanti possono evitarlo del tutto .. e fidati di me non puoi mai fare abbastanza pulizia del codice. Ma la semplice verità è che finché si mantengono i backup, è possibile [~ # ~] sempre [~ # ~] eliminare i commenti.

1
Talvi Watia

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.

1
user15127

Direi che non usare alcuni commenti nel tuo codice è un odore di codice. Anche se concordo 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 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.

1
rjzii

Devo essere d'accordo con il tuo collega. Dico sempre che se commento il mio codice, significa che sono preoccupato che I 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
0
Ken

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.
0
Maxpm

Informa il tuo collega sulla tecnica Literate Programming .

0
SK-logic

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!

0
dmuir

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

Esempi di buono commenti:

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

// Questo è un modo intelligente di fare X

// L'elenco è garantito non vuoto qui

0
Andres F.

Tuttavia, il codice che non può essere compreso affatto è un odore molto più grande di codice ...

Per favore, dammi un codice pulito su cui lavorare, comunque
se questa non è un'opzione, preferirei avere un codice "sporco" con commenti
rispetto al codice sporco senza commenti.

0
Ian

La maggior parte delle parole è stata tolta dalla mia bocca. Ma suppongo di riassumere tutto: il punto dei commenti è dare una descrizione/spiegazione di alto livello di ciò che il codice sta facendo.

Inoltre, ecco alcuni esempi di come utilizzo i commenti:

  • come intestazioni, per indicare lo scopo generale di una sezione di codice
  • notare da dove ho paralizzato il codice e quindi evitare il plagio
  • occasionalmente alle estremità dei blocchi, per ricordare di quale blocco sono la fine
  • sottolineare che il codice che può apparire sospetto è ciò che si intende (ad esempio quei tempi strani in cui cade una custodia)
  • per spiegare la matematica dietro un algoritmo
0
Stewart

Nessuno ha detto questo finora in questo thread, quindi lo farò:

I nomi dei tipi, i nomi delle variabili, i nomi delle funzioni, i nomi dei metodi e i commenti sono solo metadati del codice e non hanno nulla a che fare con il codice macchina generato dal compilatore (tranne i nomi dei simboli esportati e di debug ovviamente).

I nomi dei tipi e dei nomi delle variabili sono i tuoi nomi, i nomi delle funzioni e dei metodi sono i tuoi verbi, con questi descrivi i passi da fare. I commenti sono per tutto il resto.

Qualche esempio:

double temperature; // In Kelvins.


/**
 * Returns true if ray hits the triangle
 */
bool castRayOnTriangle(Triangle t, Ray r)
{
    //...
    if (determinant == 0)
    {
        /* The ray and the triangle are parallel, no intersection possible.*/
        return false;
    }
    //...
}


/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >

I commenti possono diventare obsoleti, se non aggiornati, ma anche i nomi delle variabili e delle funzioni possono diventare obsoleti. Di recente ho riscontrato un campo bufPtr in una struttura C, che non ha nulla a che fare con buffer o puntatori. E ho visto una funzione inflateBuffer che non decomprime i dati deflazionati ma un file GZIP completo ... Questi sono fastidiosi come commenti obsoleti.

0
Calmarius

Non sembra che troppe risposte considerino la programmazione in team. Sono uno sviluppatore senior e tendo a scrivere commenti volti a spiegare cosa è altrimenti semplice per me capire.

Lo vedo come una forma di comunicazione postuma postuma o educazione. Incoraggio il team a consultare il codice che stanno utilizzando, ma forse non hanno scritto per capirlo meglio.

Un paio di esempi proprio di questa settimana (codice PHP):

//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";

Spero che il nome PATTERN_PHOTO sarebbe utile più avanti nel codice per spiegare cosa fa, ma senza i commenti quanto sarebbe chiaro a uno sviluppatore junior cosa fa questo schema specifico?

Stesso set di codice:

//Ignore . and .. directories in Linux
if($file != "." && $file != "..")

Ci si aspetta che i nostri sviluppatori conoscano PHP, ma non che capiscano il sistema operativo Linux che stiamo usando per l'hosting.

Quindi, trovo questi commenti per aumentare effettivamente l'efficienza complessiva del nostro team per il poco tempo necessario per scriverli.

  • Ci sono meno casi di persone che riscrivono il codice semplicemente perché non capiscono come funziona. "Non ho capito come ha fatto quello che doveva, quindi l'ho risolto." Seriamente, ho dovuto occuparmene prima.
  • Ci sono meno domande sui singoli pezzi di codice. Rispondere alle domande solo una volta, di solito richiede di cercare il codice e il tempo per familiarizzare con me. E a volte ricevo la stessa domanda da più di una settimana di settimane. (Sì, sarebbe su cose semplici come gli esempi sopra)
  • Altri sviluppatori sono incoraggiati e guidati ad apprendere da soli. Mi aspetto che se si imbattessero in //Ignore . and .. directories in Linux probabilmente salterebbero su Google e improvvisamente capiranno Linux un po 'meglio.
0
Chris