Come fare la documentazione per il codice e perché il software (spesso) è scarsamente documentato?


26

Ci sono alcuni buoni esempi di codice ben documentato là fuori, come java api. Ma un sacco di codice in progetti pubblici come git e progetti interni di aziende è scarsamente documentato e non molto adatto ai nuovi arrivati.

In tutte le mie fasi di sviluppo del software, ho dovuto fare i conti con codice scarsamente documentato. Ho notato le seguenti cose:

  1. Piccoli o nessun commento nel codice.
  2. I nomi dei metodi e delle variabili non si descrivono da soli.
  3. C'è poca o nessuna documentazione su come il codice si adatta al sistema o ai processi aziendali.
  4. Assumere cattivi sviluppatori o non tutorare quelli buoni. Non possono scrivere codice semplice e pulito. Quindi è difficile o impossibile per chiunque, incluso lo sviluppatore, documentare il codice.

Di conseguenza, ho dovuto analizzare molto codice e parlare con molte persone per imparare le cose. Sento che questo fa perdere tempo a tutti. Inoltre, crea la necessità di sessioni di trasferimento KT / conoscenza per i nuovi arrivati ​​a un progetto.

Ho appreso che la documentazione non riceve l'attenzione che merita a causa dei seguenti motivi:

  1. Pigrizia.
  2. Agli sviluppatori non piace fare altro che il codice.
  3. Sicurezza sul lavoro. (Se nessuno può capire facilmente il tuo codice, potresti non essere facilmente sostituibile.)
  4. Scadenze difficili lasciano poco tempo per documentare.

Quindi, mi chiedo se esiste un modo per incoraggiare e applicare le buone pratiche di documentazione in un'azienda o in un progetto. Quali sono le strategie da utilizzare per creare una documentazione decente per i sistemi e il codice di qualsiasi progetto, indipendentemente dalla sua complessità? Ci sono buoni esempi di quando è necessaria una documentazione minima o assente?

Secondo me, dovremmo avere una revisione della documentazione dopo la consegna di un progetto. Se non è semplice, conciso, illustrativo e intuitivo, lo sviluppatore o l'ingegnere della documentazione tecnica ne è responsabile ed è tenuto a ripararlo. Non mi aspetto che le persone realizzino risme di documentazione, non spero che sia facile da usare come i primi libri di testa, ma mi aspetto che elimini la necessità di ore di analisi e sessioni KT dispendiose.

C'è un modo per porre fine o alleviare questa follia? "Sviluppo guidato da documenti" forse?


2
C'è un altro motivo per cui spesso non esiste una documentazione adeguata: è molto difficile scrivere una buona documentazione che non solo parafrasando il codice in inglese, ma descriva perché il codice è progettato / scritto in quel modo. La necessità di queste informazioni diventa evidente solo dopo mesi che avrebbero dovuto essere scritte.
Bart van Ingen Schenau,

1
Un'altra ragione seria: molti sviluppatori hanno l'inglese come seconda lingua e / o scrivono male l'inglese. Potresti semplicemente costringerli a scrivere una riga per un metodo, ma se vuoi una buona documentazione, è meglio essere preparati a pagare per questo e assumere specialisti per farlo.
david.pfx,

Risposte:


26

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.

  1. 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.

  2. 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.

  3. 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:

  1. All'inizio, il team è disposto a documentare molto.

  2. Nel tempo, la pressione delle scadenze e la mancanza di interesse rendono sempre più difficile conservare la documentazione.

  3. Pochi mesi dopo, una nuova persona che si unisce al progetto praticamente non può usare la documentazione, perché non corrisponde affatto al sistema reale.

  4. 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.


A "come incoraggiare", aggiungerei che molti IDE consentono la notifica della documentazione mancante come avvertenze. In alternativa, forse l'OSB può eseguire un'analisi statica della documentazione (ovviamente, da sola non sarebbe sufficiente).
SJuan76,

@ SJuan76: in effetti. Visual Studio può persino considerare la mancanza di commenti come un errore di compilazione. Ho modificato la mia risposta per aggiungere una nota al riguardo.
Arseni Mourzenko,

@ArseniMourzenko - Ho letto che potremmo incoraggiare un po 'di documentazione in Agile aggiungendo storie per la documentazione. Ma questi non dovrebbero bloccare le altre storie, ad esempio la definizione di altre storie di fatto, non devono includere il completamento delle storie di documentazione. Come ti sembra ?
Borat Sagdiyev il

3

Penso che dovresti fare una distinzione tra commenti e documentazione. Mentre i commenti sono descrittivi, mancano di coerenza, sono sparsi in tutto il codice. I commenti non dovrebbero mai compensare il codice che non si autodescrive abbastanza, invece dovrebbe suggerire ad altri programmatori parti complicate.

Se il codice debba essere documentato dipende dalla scala del progetto. Sicuramente ci sono persone che credono che tutto dovrebbe essere documentato, e sembra facile giustificare quel pensiero perché chi oserebbe opporsi alla documentazione documentale? Fortunatamente lo sviluppo del software non è scienza e il mondo non crolla se i dettagli dietro il tuo piccolo programma diventano oscuri. Ora per quanto riguarda un software professionale utilizzato da molti sviluppatori, sì, ovviamente, dovresti documentare il tuo codice. Ma se sei in grado di programmare su quel livello, allora lo sapresti ovviamente.

tl; dr

Se stai chiedendo che ogni progetto sia ben documentato, allora stai chiedendo troppo.


2
Fortunately software development is not sciencePer favore, dimmi di più sul perché ci credi.
Borat Sagdiyev,

3
@Borat - Lo sviluppo del software è una disciplina di ingegneria, che implica che utilizza gli strumenti forniti dalla scienza.
Leopold Asperger,

Non sto chiedendo di documentare tutto. Dovrebbe essere appena sufficiente per fornire una panoramica di alto livello di ciò che fa un sistema e un codice. Per esempio. Per favore, dimmi come usare la mia TV. Non mi interessa se utilizza LCD, CRT, tubi del vuoto o dispositivi a stato solido per svolgere il lavoro. Se un tecnico delle riparazioni desidera tali informazioni, crea una documentazione separata per lui.
Borat Sagdiyev,

Se si desidera una panoramica di alto livello, i nomi degli identificativi sono sufficienti. Proprio come il pulsante sul televisore potrebbe avere un'etichetta "On". Quindi stai chiedendo dettagli di basso livello.
Leopold Asperger,

2
@LeopoldAsperger: Penso che Borat stia parlando di documentare architettura e design, non metodi nelle classi.
Arseni Mourzenko,
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.