Studi sugli utili / perdite di produttività della documentazione del codice

Dopo molte ricerche, non sono riuscito a rispondere a una domanda di base relativa a un presunto noto nel mondo dello sviluppo del software:

COSA CONOSCE:

L'applicazione di una rigorosa politica sulla documentazione adeguata del codice (siano essi tag Doxygen, Javadoc o semplicemente un'abbondanza di commenti) aggiunge costi generali al tempo necessario per sviluppare il codice.

MA:

Avere una documentazione approfondita (o persino un'API) porta con sé aumenti di produttività (si presume) in sviluppatori nuovi e esperti quando aggiungono funzionalità o correggono bug lungo la strada.

LA DOMANDA:

Il tempo di sviluppo aggiuntivo è necessario per garantire tale documentazione compensata dagli aumenti della produttività su strada (in senso strettamente economico)?

Sto cercando casi di studio o risposte che possano portare con sé prove oggettive a supporto delle conclusioni tratte.

Grazie in anticipo!

L'articolo "Lo stile tipografico è più che cosmetico" è piuttosto vecchio ma è molto interessante: http://portal.acm.org/citation.cfm?id=78611 .

Essendo vecchio, non include tutte le cose la fantasia che sarebbe possibile in questi giorni, ma mostra chiaramente che la documentazione del codice non importa.

Per coloro che, come me, non hanno accesso alla biblioteca digitale ACM, hanno creato due gruppi di programmatori e hanno dato loro lo stesso codice per studiare. Il gruppo A ha ricevuto solo il codice con i soliti commenti, il gruppo B ha ricevuto un elenco abbastanza stampato con sommario, riferimenti incrociati e tutte le bellezze possibili nel 1990.

Quindi hanno chiesto ai due gruppi di eseguire determinate attività sul codice (ad esempio estendere una funzione, trovare un bug, ...) e assegnarle un punteggio in termini di velocità e qualità delle risposte.

Per bilanciare il gruppo avevano lo stesso numero di programmatori esperti e junior.

Bene, si è scoperto che il gruppo B (quello con un elenco piuttosto stampato) ha ottenuto un punteggio migliore rispetto al gruppo A in numerosi test. E, in casi specifici, solo i più esperti del gruppo A sono riusciti a superare il programmatore junior del gruppo B.

L'articolo dice di più ma questo è ciò che posso ricordare dalla memoria (dovrei ancora avere l'articolo stampato da qualche parte).

Almeno per me, sembra ovvio che il codice leggibile valga molto di più della documentazione che serve solo a compensare il codice scritto male. Tendo a considerare i commenti nel codice come una sfida per vedere se riesco a rimuovere il commento riscrivendo il codice e rendendolo più autoesplicativo.

Non posso sostenerlo con alcuna prova concreta, tranne che per il buonsenso.

Non ho studi da citare, ma ho una semplice regola: se torno al mio codice due settimane dopo e non riesco a capire immediatamente cosa ho fatto, o ha bisogno di più commenti o deve essere semplificato .

Certamente, come funziona il tuo codice dovrebbe essere documentato dal codice stesso. Ma il tempo speso a scrivere commenti che spiegano attentamente e in modo conciso perché il tuo codice è scritto nel modo in cui è quasi certamente ripaga da solo a lungo termine, anche se sei l'unica persona che mantiene il codice.

La durata di un pezzo di software sarà spesa principalmente nella fase di manutenzione, quindi tutto ciò che aiuta il programmatore a venire dopo di te per capire cosa sta succedendo fornirà quasi sicuramente rendimenti finanziari, perché aiuta lo sviluppatore a velocizzare più velocemente.

Su qualsiasi API che sia leggermente non banale documentare l'API nel codice è quasi inutile. Questo perché la potenza dell'API deriva da come funziona insieme come un'unità intera (non come funzionano singoli metodi / oggetti).

Quindi più utile della vera documentazione è un documento simile a un libro di cucina che spiega i modelli di utilizzo previsti dell'API ed esempi di come risolvere alcune situazioni ovvie (che utilizzano la maggior parte (non il 100%) dell'API).

La decisione se un determinato metodo sia, senza strumenti che probabilmente non sono ancora stati inventati, è troppo soggettiva per richiedere che la documentazione sia scritta.

Qualsiasi pratica di ipotesi, come "tutti i metodi pubblici" o tutte le classi in un determinato pacchetto, ecc., Può essere d'aiuto, ma è troppo approssimativa per raccomandare al di là di casi d'uso specifici.

Il mio suggerimento: insegnare ai vostri sviluppatori buone pratiche, come identificare i metodi che sono importanti per documentare (API formale o informale, API comunemente usate, metodi stub, complessi o esoterici) e lasciarli governare da soli.

(Strettamente correlato: può esserci troppa uniformità negli standard di codifica? )

^{Mi scuso se non ho studi da citare, ma sospetto che questo sia un problema in cui qualsiasi tentativo di misurarlo influirebbe troppo sul risultato per trarre conclusioni generali.}

Penso che a questo proposito dobbiamo separare il codice "normale" dalle API pubbliche . Per il codice normale sono arrivato a concordare con la maggior parte degli altri rispondenti in quel codice che dovrebbero essere auto-documentati e letti quasi come in prosa . Se il mio codice non è così, di solito è colpa mia, quindi piuttosto che documentare, dovrebbe essere refactored. Piccoli metodi che fanno solo una cosa alla volta, lavorando su un singolo livello di astrazione, con un nome corretto e descrittivo , possono fare molto per raggiungere questo obiettivo.

Il problema con i commenti è che marciscono. Non appena aggiungi un commento, inizia a vivere una vita indipendente dal codice che accompagna. Quanto è grande la possibilità che il prossimo sviluppatore che modifica il codice aggiorni debitamente anche i commenti relativi? Nella mia esperienza, vicino a zero. Il risultato finale dopo alcune modifiche è che il commento confonde o induce in errore le persone invece di aiutarle.

Le possibili eccezioni sono il codice ottimizzato per le prestazioni o l'utilizzo di un algoritmo specifico . In questo caso è utile aggiungere commenti per descrivere il motivo per cui appare il codice, un riferimento all'algoritmo ecc.

Il lavoro fondamentale su questo argomento è Clean Code .

OTOH un'API pubblica dovrebbe davvero essere ben documentata anche in Javadoc . Dal momento che può essere utilizzato da innumerevoli estranei totali con abilità e ipotesi selvaggiamente diverse, si devono prendere tutte le precauzioni per renderlo il più semplice e chiaro possibile da usare. Questa è ancora in gran parte una questione di corretta progettazione dell'API, ma c'è anche un ruolo importante per la documentazione.

Il problema è se risparmi tempo documentando il tuo codice rispetto a ogni sviluppatore successivo che deve cercare di capire cosa fa. Se il tuo codice passa attraverso la revisione del codice senza che nessuno porti domande su ciò che fa, probabilmente sei in buona forma. Non è troppo difficile descrivere le ipotesi fatte sugli input. Diciamo che il tuo metodo prende un oggetto intero e restituisce un oggetto stringa. L'int può essere nullo? Esiste un valore min / max (oltre a integer.MinValue / MaxValue)? Può restituire una stringa vuota o nulla? Fa delle eccezioni? Ovviamente chiunque può trovarli tramite ispezione, ma se un numero sufficiente di altri sviluppatori utilizzerà il tuo codice, vale la pena dedicare del tempo a ciascuno di essi. Inoltre, fornisce ai tester un vantaggio sulla creazione di test per confermare il codice.

Questo è sicuramente un argomento interessante in quanto vi sono sempre state discussioni sul fatto che lo sviluppatore debba dedicare del tempo alla creazione o alla gestione di documenti o meno, ma il fatto è che il codice deve essere ben scritto e commentato molto bene, in questo modo quando lo sviluppatore visita nuovamente il codice di lui o lei non deve passare il tempo a riflettere su come è stato scritto il codice e su cosa avrebbe dovuto fare in primo luogo se un nuovo membro del team si unisce al team di quanto possa anche comprendere la funzionalità e il funzionamento del codice come è stato chiaramente documentato.

Quindi il codice dovrebbe essere molto ben commentato e quindi dovrebbe essere un codice autodocumentato che non richiede alcuna documentazione esterna.

Nella mia carriera, ho visto codice con diversi livelli di documentazione e qualità (nota che la documentazione e la qualità sono preoccupazioni ortogonali). Preferirei che il tempo dedicato alla documentazione venisse utilizzato per migliorare la qualità. Per il semplice caso ci sono strumenti come GhostDoc che possono guardare una funzione e generare commenti doc per te. Se GhostDoc può generare un commento significativo che dice cosa fa la tua funzione, allora hai ovviamente raggiunto l'obiettivo di avere funzioni ben denominate.

In molti casi, GhostDoc non può nemmeno iniziare a dirti cosa fa realmente una funzione. È meglio passare il tempo a risolvere il problema e (forse) a utilizzare ghostdoc per generare automaticamente il codice.

Vedi Clean Code e PPP di Bob Martin per una discussione più approfondita.