Come documentare il codice?
Hai già un suggerimento: guarda come è documentata l'API Java.
Più in generale, non esiste un insieme unico di regole che si applicano a ogni progetto. Quando lavoro su progetti su larga scala fondamentali per il business, la documentazione non ha nulla a che fare con quella che scrivo per una piccola biblioteca open source, che a sua volta non ha nulla a che fare con la documentazione del mio progetto personale su media scala .
Perché molti progetti open source non sono ben documentati?
Perché la maggior parte dei progetti open source sono realizzati da persone che contribuiscono a questi progetti perché è divertente. La maggior parte dei programmatori e sviluppatori ritiene che la scrittura di documentazione non sia abbastanza divertente da essere eseguita gratuitamente.
Perché molti progetti a sorgente chiuso non sono ben documentati?
Perché costa una grande quantità di denaro per (1) scrivere una buona documentazione e per (2) mantenerla.
Il costo immediato (costo della stesura della documentazione) è chiaramente visibile agli stakeholder: se il tuo team chiede di spendere i prossimi due mesi per documentare il progetto, è necessario pagare due mesi in più di stipendio.
Il costo a lungo termine (costo di mantenimento della documentazione) diventa evidente anche per i gestori, ed è spesso il primo obiettivo quando devono abbassare i costi o ridurre i ritardi. Ciò causa un ulteriore problema di documentazione obsoleta che diventa rapidamente inutile ed è estremamente costoso da aggiornare.
I risparmi a lungo termine (risparmi derivanti dal fatto di non dover perdere qualche giorno ad esplorare il codice legacy solo per capire una cosa di base che avrebbe dovuto essere documentata anni fa) sono, invece, difficili da misurare, il che conferma la sensazione di alcuni manager che scrivere e conservare la documentazione è una perdita di tempo.
Quello che osservo spesso è che:
All'inizio, il team è disposto a documentare molto.
Nel tempo, la pressione delle scadenze e la mancanza di interesse rendono sempre più difficile conservare la documentazione.
Pochi mesi dopo, una nuova persona che si unisce al progetto praticamente non può usare la documentazione, perché non corrisponde affatto al sistema reale.
Notando che, la gestione incolpa gli sviluppatori per non mantenere la documentazione; gli sviluppatori chiedono di passare qualche settimana ad aggiornarlo.
Se la gestione concede alcune settimane per questo, il ciclo si ripete.
Se la gestione rifiuta, sulla base dell'esperienza precedente, aumenta solo la brutta esperienza, poiché il prodotto manca di documentazione, ma sono stati spesi alcuni mesi per scriverlo e mantenerlo.
La documentazione dovrebbe essere un processo continuo, proprio come i test. Trascorrere una settimana semplicemente codificando alcune migliaia di LOC e tornare ai test e alla documentazione è molto, molto doloroso.
Come incoraggiare il team a scrivere documentazione?
Analogamente ai modi per incoraggiare le persone a scrivere codice pulito, eseguire regolarmente refactoring, utilizzare schemi di progettazione o aggiungere test unitari sufficienti.
Dare l'esempio. Se scrivi buona documentazione, anche le tue coppie potrebbero iniziare a farlo.
Esegui revisioni sistematiche del codice, comprese revisioni formali del codice mirate all'ispezione della documentazione.
Se alcuni membri del team sono particolarmente antipatici per una buona documentazione (o per nulla documentazione), discuti l'argomento con loro privatamente, per capire quali sono gli impedimenti che impediscono loro di scrivere una migliore documentazione. Se danno la colpa alla mancanza di tempo, vedi l'origine dei problemi.
Rendi misurabile la presenza o la mancanza di documentazione per alcune settimane o mesi, ma non concentrarti su questo. Ad esempio, puoi misurare il numero di righe di commenti per LOC, ma non renderlo una misura permanente, altrimenti gli sviluppatori inizieranno a scrivere commenti lunghi ma privi di significato solo per sbarazzarsi di punteggi bassi.
Usa la gamification. Questo si unisce al punto precedente.
Usa rinforzo positivo / negativo .
(Vedi il commento di SJuan76 ) Tratta la mancanza di commenti come errori. Ad esempio, in Visual Studio, è possibile selezionare un'opzione per generare documentazione XML. Se controlli anche che tutti gli avvisi siano trattati come errori, la mancanza di un commento all'inizio di una classe o di un metodo interromperà la compilazione.
Per quanto riguarda i tre punti precedenti, questo dovrebbe essere usato con cautela. L'ho usato per un po 'con un team particolarmente duro di programmatori principianti, e si è concluso con commenti conformi a StyleCop come questo:
/// <summary>
/// Gets or sets the PrimaryHandling.
/// </summary>
public Workflow PrimaryHandling { get; set; }
che erano, hm ..., non particolarmente utili.
Ricorda: nulla di automatizzato può aiutarti a individuare commenti negativi quando i programmatori vogliono rovinare te . Solo le revisioni del codice e altre attività umane saranno di aiuto.
Ci sono buoni esempi di quando è necessaria una documentazione minima o assente?
Non è necessaria la documentazione che spieghi l'architettura e il design :
Per un prototipo,
Per un progetto personale scritto tra poche ore per eseguire un'attività, pur essendo abbastanza sicuro che questo progetto non verrà più mantenuto,
Per qualsiasi progetto in cui è ovvio, date le sue dimensioni ridotte, unito al codice particolarmente pulito, che dedichi più tempo a scrivere documentazione di tutti i futuri manutentori che esplorano il codice.
La documentazione nel codice (commenti sul codice) non è necessaria secondo alcuni sviluppatori quando il codice è autocompattante. Per loro, la presenza di commenti è, tranne in rari casi, non un buon segno, ma un segno che il codice non è stato riformulato abbastanza per essere chiaro senza la necessità di commenti.
Ritengo che dovremmo avere una revisione della documentazione dopo la consegna di un progetto.
Se il tuo progetto viene consegnato almeno una volta alla settimana, è la strada da percorrere. Se il tuo progetto non è agile e viene consegnato a intervalli di sei mesi, fai revisioni più regolari.