I commenti obsoleti sono un mito urbano?

Vedo costantemente persone affermare che "i commenti tendono a diventare obsoleti". Il fatto è che penso di aver visto forse due o tre commenti obsoleti per tutta la mia carriera. Le informazioni obsolete in documenti separati avvengono continuamente, ma nella mia esperienza i commenti obsoleti nel codice stesso sono estremamente rari.

Sono stato solo fortunato con chi lavoro? Alcuni settori sono più inclini a questo problema rispetto ad altri? Hai esempi specifici di recenti commenti obsoleti che hai visto? O i commenti obsoleti sono più un problema teorico che reale?

costantemente

Non riesco davvero a credere di essere l'unico a nuotare in commenti obsoleti e fuorvianti. In caso contrario ciò aiuta a comprendere:

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

Faccio parti uguali di ricerca e sviluppo e lavori di manutenzione. La ricerca e sviluppo è un nuovo codice, generalmente roba un po 'fuori mano. Molti dei miei colleghi credono nel fornire molte spiegazioni commentate quando provano qualcosa per cui non esiste già una biblioteca. Poiché il rapporto commento / codice è più alto del normale, ci sono solo più opportunità che le cose vadano fuori sincrono.

Il codice di manutenzione ... Sono un manutentore attivo di un sistema di oltre 10 anni e un altro di oltre 5. Il codice e i commenti di 10 anni sono atroci, come ci si aspetterebbe. In 10 anni hai un sacco di mani nel codebase e nessuno ha idea di come funzioni tutto. Il codice e i commenti di 5 anni sono abbastanza buoni perché il turnover del team è stato piuttosto basso.

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

Esempi specifici:

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

• TODOs

• Blocchi di codice incollato con copia inclusi i commenti. Il commento potrebbe avere un senso nella sua posizione originale, ma qui non ha molto senso

• Blocchi di commenti in cima al codice commentato (chissà quanti anni ci sono stati).

In tutti questi si nota la tendenza a non mantenere i commenti e il codice allo stesso livello del software. Gli IDE e le abitudini di base degli sviluppatori non aiutano in questo, il mio occhio è stato addestrato per superarli. Penso che commenti obsoleti siano relativamente economici da evitare nei progetti in campo verde e attivi. Se riesci a mantenere alto il rapporto codice / commento, non è un grosso problema tenerli aggiornati. È un po 'più difficile giustificare la caccia a queste cose quando si è in budget x ore per una correzione di bug su un sistema di produzione.

"i commenti tendono a diventare obsoleti".

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

Il fatto è che penso di aver visto forse due o tre commenti obsoleti per tutta la mia carriera.

Credo che dovrebbe essere 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 appropriato. Nel caso in cui i commenti siano così lontani che non li noti immediatamente, erano comunque commenti negativi e non avrebbero dovuto essere aggiunti in primo luogo (o almeno non lì).

Inoltre, di solito insieme all'affermazione secondo cui i commenti tendono a diventare obsoleti, segue l'affermazione secondo cui 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ù.

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

21 partecipanti [su 28] hanno riferito di ottenere le loro informazioni principali dal codice sorgente e di commenti in linea, mentre solo quattro hanno dichiarato che la documentazione è la loro principale fonte di informazioni.

Ciò è in linea con il tuo sospetto che i commenti nel codice stesso siano generalmente considerati molto utili. Ciò indica che è necessario tracciare una linea chiara tra la documentazione obsoleta e i commenti non aggiornati .

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

I commenti obsoleti sono un odore di lavoro. È come avere test unitari obsoleti o trascurati - mostra che i buoni processi che una volta erano attivi nel negozio stanno degenerando nella codifica da cowboy. La corretta "cultura ingegneristica" di prendere il tempo necessario per fare le cose nel modo giusto si è rotta. È probabile che il progetto / azienda stia andando in debito tecnico.

In breve, sì, sei stato fortunato. Se finora ti è capitato di avere una serie di negozi ragionevolmente ben gestiti nella tua carriera, è del tutto possibile non vedere così tanto. Ma in negozi più tipici, meno gestiti, questo è parallelo al resto del caos.

I commenti sono come dei test, sono molto utili quando sono aggiornati, ma possono rendere ancora più difficile la comprensione del codice se non lo 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 ignoro completamente i commenti poiché di solito sono fonte di confusione anziché aiuto.

I commenti obsoleti appaiono spesso in JavaDoc:

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

Inoltre, a volte i commenti affermano 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.

Di tanto in tanto mi occupo di commenti obsoleti. Certamente non è un mito urbano. La gente lo menziona negli elenchi delle peggiori pratiche non perché ti colpisce molto spesso ma perché quando lo fa, di solito ti costa molto tempo e fatica.

Nella nostra base di codice la maggior parte dei commenti 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 un lungo pezzo di codice in un metodo che viene chiamato solo una volta al momento e quindi commenta la chiamata del metodo. Quindi finisci con qualcosa del genere:

featureList = GetFeatures();

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

E il metodo è dichiarato da qualche parte in basso senza commenti. Nel corso degli anni le persone si sono scontrate con questi metodi per gestire le modifiche alle specifiche e correggere i bug e alla fine si ottiene 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à del tempo nel debugger. Ciò accade in alcune basi di codice.

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 i commenti a volte non sono nemmeno vicini al pertinente.

Per la maggior parte, la mia esperienza corrisponde alla tua, ma ho riscontrato un caso in cui ciò era vero in tutta la base di codice. 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 mantenuto dal momento del trasferimento originale facevano parte della mentalità "cambia solo ciò che deve assolutamente essere cambiato" che di per sé non è male. Sfortunatamente, hanno mantenuto lo stesso atteggiamento anche nei confronti dei commenti, portando a una disconnessione piuttosto ampia tra i commenti e il codice nel tempo.

Non vedo troppi commenti descrittivi diventare obsoleti, ma vedo molti commenti TODO presenti da anni. Vorrei che fossero come capsule del tempo e dicessero qualcosa del genere:

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

Negli ultimi 3 progetti a cui ho lavorato, ho trascorso diversi giorni a rimuovere tutti i commenti obsoleti, fuorvianti e semplicemente inutili dalla base di codice. 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 praticamente su ogni base di codice che io abbia mai preso in consegna da altri, di solito dopo che non è stato mantenuto per un po 'e che i proprietari originali se ne sono andati da tempo e / o non sono disposti o incapaci di fare il passaggio di consegne.

Potrebbe essere il declino nell'uso dei commenti. Quanto del codice di qualcuno si qualifica? Per uno, qualcuno deve effettivamente includere commenti per essere obsoleti. In secondo luogo, il codice che è stato commentato deve essere modificato. Non sono sicuro che un'alta percentuale di codice si qualifichi.

Devi solo fare affidamento su un brutto commento per rovinare una grande parte di un'applicazione e perdere molto tempo.

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