I commenti obsoleti sono un mito urbano?

Costantemente

Non riesco davvero a credere di essere l'unico a nuotare in commenti obsoleti e fuorvianti. Nel caso questo ti aiuta a capire:

Probabilmente dipende soprattutto dall'età del codice. Il prossimo fattore sarebbe il turnover sul personale.

Faccio le stesse parti R & D e lavori di manutenzione. La R & D è un nuovo codice, in genere roba un po 'fuori mano. Molti dei miei colleghi credono nel mettere molte spiegazioni commentate quando provano qualcosa per cui non esiste già una biblioteca. Dal momento che il rapporto tra il commento e il codice è più alto del normale ci sono ancora più opportunità per le cose di andare fuori sincrono.

Il codice di manutenzione ... Sono un manutentore attivo su un sistema che ha più di 10 anni e un altro che ha più di 5. Il codice e i commenti di 10 anni sono atroci, come ci si aspetterebbe. Più di 10 anni hai un sacco di mani nella base di codice e nessuno ha idea di come funzioni l'intera cosa. Il codice e i commenti di 5 anni sono abbastanza buoni perché il turnover della squadra è stato piuttosto basso.

Lavoro quasi tutti i servizi, anche i nostri prodotti sono altamente personalizzati per un determinato cliente.

Esempi specifici:

• Commenti che descrivono il miglioramento delle prestazioni per una particolare metodologia, come evitare una copia in memoria. Un grosso problema quando una macchina di fascia alta in un Pentium 2 con MB di RAM, ma difficilmente un problema ora.

• TODOs

• Blocchi di codice incollato sulla copia, inclusi commenti. Il commento può avere senso nella sua posizione originale, ma non ha senso qui

• I blocchi di commento in cima al codice commentato (Chissà quanti anni ci sono stati)

In tutti questi si vede una tendenza a non mantenere i commenti e il codice allo stesso livello del software. Gli IDE e le abitudini di sviluppo di base non aiutano in questo modo, i miei occhi sono stati addestrati a velocizzarli. Penso che i commenti obsoleti siano relativamente economici da evitare in progetti attivi e in campo verde. Se riesci a mantenere alto il rapporto codice / commento, non è un grosso problema mantenerli aggiornati. È un po 'più difficile giustificare la caccia di queste cose quando hai un budget di x ore per una correzione di bug su un sistema di produzione.

"comments tend to become outdated."

Ho visto questo accadere abbastanza spesso da sapere che questo può essere un problema.

The thing is, I think I have seen maybe two or three outdated comments my entire career.

Credo che sia perfettamente possibile lavorare in un ambiente in cui tutti si prendono abbastanza cura dei commenti e li mantengono. È solo un piccolo sforzo in più per guardare i commenti vicino al codice che stai modificando e aggiornarli quando opportuno. Nel caso in cui i commenti siano così lontani da non essere immediatamente notati, erano comunque commenti negativi e non avrebbero dovuto essere aggiunti in primo luogo (o almeno non lì).

Inoltre di solito insieme alla dichiarazione che i commenti tendono a diventare obsoleti, segue la dichiarazione che ciò riduce la leggibilità e confonde le persone. Questo è qualcosa che non ho ancora sperimentato. Ogni volta che incontro un commento non aggiornato, vedo chiaramente cosa è cambiato e aggiorno il commento di conseguenza per rappresentare il codice più recente, anche se con qualche sforzo in più.

Uno studio recente di Roehm et al. 2012 osserva quanto segue:

21 participants [out of 28] reported that they get their main information from source code and inline comments whereas only four stated that documentation is their main source of information.

Questo è in linea con il tuo sospetto che i commenti nel codice stesso siano ancora considerati molto utili. Ciò indica che deve essere tracciata una linea chiara tra la documentazione obsoleta e i commenti obsoleti .

_{Roehm, T., Tiarks, R., Koschke, R., & Maalej, W. (2012, giugno). In che modo gli sviluppatori professionisti comprendono il software? In Atti della Conferenza internazionale del 2012 sull'ingegneria del software (pagine 255 -265). IEEE Press.}

I commenti obsoleti sono un odore di lavoro. È come avere test unitari obsoleti o trascurati: dimostra che i buoni processi che una volta erano attivi nel negozio stanno degenerando nella codifica dei cowboy. La corretta "cultura ingegneristica" di prendersi del tempo per fare le cose correttamente è fallita. Il progetto / azienda è probabile che entri in debito tecnico.

In breve, sì, sei stato fortunato. Se ti è capitato di avere una serie di negozi ragionevolmente ben gestiti nella tua carriera, è abbastanza probabile non vederlo molto. Ma nei negozi più tipici, meno ben gestiti, questo funziona parallelamente al resto del caos.

I commenti sono come test, sono molto buoni quando sono aggiornati, ma possono rendere ancora più difficile capire il codice se non ci sono.

Se non hai mai visto commenti obsoleti, sei stato molto fortunato.

La maggior parte delle basi di codice con cui ho lavorato è stata piena di commenti obsoleti, e di solito trascuro completamente i commenti poiché di solito sono fonte di confusione invece di aiuto.

I commenti obsoleti appaiono spesso in JavaDoc:

• Elenca argomenti che non esistono più
• Non spiega tutti gli argomenti (quelli mancanti sono stati probabilmente aggiunti in seguito)
• Cose simili per eccezioni, ecc.

Inoltre, a volte i commenti dicono cose come "fai questo qui per le prestazioni" quando la maggior parte delle considerazioni sulle prestazioni tendono a diventare obsolete anche più velocemente del codice stesso.

Mi occupo di commenti obsoleti di volta in volta. Non è certamente un mito urbano. La gente lo menziona nelle liste delle peggiori pratiche, non perché ti colpisce molto spesso, ma perché quando lo fa, di solito ti costa un sacco di tempo e fatica.

Nel nostro codebase i commenti più obsoleti sono causati dall'uso del modello (anti) di descrizione del comportamento del metodo vicino alla sua chiamata e non vicino alla dichiarazione del metodo. Succede quando qualcuno estrae una lunga porzione di codice in un metodo che viene chiamato solo una volta al momento e quindi commenta la chiamata al metodo. Quindi si finisce con qualcosa di simile:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

E il metodo è dichiarato da qualche parte qui sotto senza commenti. Le persone si pasticciano con questi metodi nel corso degli anni affrontando cambiamenti di specifiche e bug di correzione, e alla fine si finisce con un metodo che non ordina l'elenco e genera un'eccezione quando trova la funzione vuota. Quindi il commento sopra è un commento obsoleto che alla fine ti costerà un po 'di tempo nel debugger. Questi si verificano in alcune codebase.

Chiediti questo. Hai mai cambiato una riga di codice e non hai modificato i commenti associati o ne hai aggiunti di nuovi?

Ho lavorato con un sacco di codice legacy e talvolta i commenti non sono nemmeno vicini a pertinenti.

Per la maggior parte, la mia esperienza corrisponde alla tua ma ho attraversato un caso in cui ciò era vero per tutto il codice base. Era un'app che era stata scritta anni prima da un negozio di consulenza che non era più "in buoni rapporti" con il cliente.

La società ha fatto un lavoro eccezionale commentando il codice, ma i programmatori che l'hanno mantenuta dopo il passaggio iniziale facevano parte della mentalità "cambia solo ciò che è assolutamente necessario cambiare" che di per sé non è male. Sfortunatamente, hanno mantenuto lo stesso atteggiamento nei confronti dei commenti, causando una disconnessione piuttosto ampia tra i commenti e il codice nel tempo.

Non vedo troppi commenti descrittivi che non sono aggiornati, ma vedo molti commenti TODO che ci sono stati da anni. Vorrei che fossero come capsule del tempo e ho detto qualcosa del genere:

//TODO: In 15 years AND NO SOONER... actually implement this method.

Ultimi 3 progetti su cui ho lavorato Ho trascorso diversi giorni eliminando commenti obsoleti, fuorvianti e semplicemente inutili dal codice base. Laddove possibile e necessario, li sostituisco con commenti più appropriati, ma il più delle volte si tratta solo di eliminare il commento e andare avanti.

Ho fatto lo stesso su praticamente tutti i codebase che ho mai preso dagli altri, di solito dopo che è stato mantenuto invariato per un po 'ei proprietari originali se ne erano andati da tempo e / o non volevano o non erano in grado di fare il passaggio.

Potrebbe essere il declino nell'uso dei commenti. Quanto del codice di qualcuno è qualificato? Per uno, qualcuno in realtà deve includere commenti per loro essere obsoleti. In secondo luogo, il codice che è stato commentato deve essere cambiato. Non sei sicuro che un'alta percentuale di codice sia idonea.

Devi solo fare affidamento su un commento negativo per rovinare una grande parte di un'applicazione e sprecare un sacco di tempo.

In un'organizzazione che sforna molto codice, è difficile mantenere i commenti sincronizzati. Il modo migliore per capire cosa sta succedendo è usando software che disegnano il diagramma di flusso di controllo del modulo su cui stai lavorando. Questo è l'unico modo per avere un'idea di cosa fa il software.