Studi su guadagni / perdite di produttività della documentazione del codice

L'articolo "Lo stile tipografico è più che cosmetico" è piuttosto vecchio ma è molto interessante: link .

Essendo vecchio, non include tutte le cose di fantasia che sarebbero possibili in questi giorni ma mostra chiaramente che la documentazione del codice è importante.

Per coloro che, come me, non hanno accesso alla libreria digitale ACM, hanno creato due gruppi di programmatori e hanno dato loro lo stesso codice da studiare. Il gruppo A ricevette solo il codice con i soliti commenti, il gruppo B ricevette una lista stampata con indice, riferimenti incrociati e tutte le sottigliezze che erano possibili nel 1990.

Quindi hanno chiesto ai due gruppi di eseguire determinati compiti sul codice (ad esempio estendere una funzione, trovare un bug, ...) e li hanno valutati 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 abbastanza stampato) ha ottenuto punteggi migliori 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 comunque avere l'articolo stampato da qualche parte).

Per me almeno, 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ù auto esplicativo.

Non posso sostenerlo con prove concrete, eccetto il buon senso.

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

Certamente, in che modo il tuo codice funziona dovrebbe essere documentato dal codice stesso. Ma il tempo trascorso a scrivere commenti che spiegano con attenzione e sinteticamente perché il tuo codice è scritto nel modo in cui quasi sicuramente si ripaga a lungo termine, anche se sei l'unica persona che mantiene il codice.

La durata di un software verrà spesa principalmente nella fase di manutenzione, quindi tutto ciò che aiuta il programmatore a venire dopo di te a capire cosa sta succedendo fornirà quasi certamente dei ritorni finanziari, perché aiuta lo sviluppatore a diventare più veloce .

Su qualsiasi API leggermente non banale che documenta l'API nel codice è praticamente inutile. Questo perché la potenza dell'API deriva dal modo in cui funziona insieme come un'unità intera (non come funzionano i 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 su come risolvere alcune situazioni ovvie (che utilizzano la maggioranza (non al 100%) dell'API).

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

Qualsiasi pratica di best-guess, come "tutti i metodi pubblici" o tutte le classi in un determinato pacchetto, ecc. possono essere d'aiuto, ma sono troppo difficili da consigliare al di là di casi d'uso specifici.

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

(Strettamente correlato: Può esserci essere troppo uniformi negli standard di codifica? )

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

Penso che dobbiamo separare il codice "normale" dalle API pubbliche a questo riguardo. Per il codice regolare sono giunto ad essere strongmente d'accordo con la maggior parte degli altri rispondenti in quanto il codice dovrebbe essere auto-documentante e leggere quasi come la prosa . Se il mio codice non è così, di solito è colpa mia, quindi piuttosto che documentare, dovrebbe essere refactored. I piccoli metodi che fanno una sola cosa alla volta, lavorando su un singolo livello di astrazione, con un nome corretto e descrittivo , possono fare un ottimo modo 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 diligentemente anche i commenti correlati? Nella mia esperienza, vicino allo zero. Il risultato finale dopo alcune modifiche è che il commento indaga o induce in errore le persone invece di aiutarle.

Eventuali 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 il codice è simile, un riferimento all'algoritmo ecc.

Il lavoro fondamentale su questo argomento è Pulisci codice .

OTOH un'API pubblica dovrebbe essere ben documentata anche in Javadoc . Dal momento che può essere utilizzato da innumerevoli estranei con abilità e supposizioni selvagge, bisogna fare tutte le precauzioni per renderlo il più semplice e non ambiguo possibile. Questo è ancora in gran parte una questione di corretta progettazione dell'API, ma c'è anche un ruolo importante per la documentazione.

Il problema è se si risparmia tempo documentando il proprio codice rispetto a ogni sviluppatore successivo che deve cercare di capire cosa fa. Se il tuo codice vola attraverso la revisione del codice senza che nessuno faccia domande su ciò che fa, probabilmente sei in buona forma. Non è troppo difficile descrivere le ipotesi che fai 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? Genera eccezioni? Naturalmente chiunque può trovarli tramite ispezione, ma se un numero sufficiente di altri sviluppatori sta per utilizzare il codice, è consigliabile risparmiare un paio di minuti. Inoltre, dà ai tester un vantaggio nella creazione di test per confermare il codice.

Questo è sicuramente un argomento interessante in quanto ci sono sempre state discussioni sul fatto che lo sviluppatore debba dedicare tempo a creare o mantenere documenti o no, ma il fatto è che il codice dovrebbe essere ben scritto e ben commentato, in questo modo quando lo sviluppatore re-visita il codice lui o lei non deve passare il tempo a riflettere su come è stato scritto il codice e cosa dovrebbe fare in primo luogo, inoltre, se il nuovo membro del team si unisce al team di quello che può anche capire la funzionalità e il funzionamento del codice come è stato chiaramente documentata.

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

Nella mia carriera, ho visto codice con vari livelli di documentazione e qualità (nota che la documentazione e la qualità sono preoccupazioni ortogonali). Preferirei utilizzare il tempo dedicato alla documentazione per migliorare la qualità. Per il caso semplice ci sono strumenti come GhostDoc che possono guardare una funzione e generare commenti 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 definite.

In molti casi, GhostDoc non può nemmeno iniziare a dirti cosa realmente fa una funzione. Il tuo tempo è speso meglio per risolvere quel problema e (forse) usare ghostdoc per generare automaticamente il tuo codice.

Vedi Pulisci codice e PPP di Bob Martin per una discussione più approfondita.