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

In tutti i miei periodi di sviluppo del software, ho avuto a che fare con codice scarsamente documentato. Ho notato le seguenti cose:

  1. Pochi 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 inserisce nel sistema o nei processi aziendali.
  4. Assumere sviluppatori cattivi o non fare da mentore a 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 passare attraverso molte programmare e parlare con molte persone per imparare le cose. Sento che questo fa perdere tempo a tutti. Crea anche la necessità di sessioni di trasferimento di KT / Conoscenze per i nuovi arrivati a un progetto.

Ho imparato che alla documentazione non viene data lattenzione che merita per i seguenti motivi:

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

Quindi, mi chiedo se esiste un modo per incoraggiare e applicare buone pratiche di documentazione in unazienda 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 nulla?

IMHO, credo che dovremmo avere una revisione della documentazione dopo la consegna di un progetto. Se non è semplice, conciso, illustrativo e di facile utilizzo, lo sviluppatore o lingegnere della documentazione tecnica ne è responsabile e deve essere incaricato di risolverlo. Non mi aspetto che le persone creino risme di documentazione, Non spero che sarà facile da usare come i primi libri di testa, ma mi aspetto che elimini la necessità di ore di analisi e inutili sessioni di KT.

Cè un modo per porre fine o alleviare questa follia? Forse “sviluppo guidato dai documenti”?

Commenti

  • Cè un altro motivo per cui spesso non cè una documentazione adeguata: è molto difficile scrivere una buona documentazione che non ‘ Basta parafrasare il codice in inglese, ma descrive perché il codice è stato progettato / scritto in questo modo. La necessità di queste informazioni diventa ovvia solo mesi dopo che avrebbero dovuto essere scritte.
  • Un altro motivo serio: molti sviluppatori hanno linglese come seconda lingua e / o lo scrivono male . Potresti semplicemente costringerli a scrivere una frase per un metodo, ma se vuoi una buona documentazione è meglio essere preparati a pagare per questo e assumere specialisti per farlo.

risposta

Come documentare il codice?

Hai già un suggerimento: guarda come è documentata lAPI Java.

Più in generale, non esiste un insieme unico di regole che si applicano a ogni progetto. Quando lavoro su grandi progetti business-critical, la documentazione non ha nulla a che fare con quella che scriverei per una piccola libreria open source, che a sua volta non ha nulla a che fare con la documentazione del mio progetto personale di media scala .

Perché molti progetti open source non sono documentati bene?

Perché la maggior parte dei progetti open source sono realizzati da persone che contribuiscono a quei progetti perché è divertente. La maggior parte dei programmatori e sviluppatori considera che scrivere documentazione non è abbastanza divertente da fare gratuitamente.

Perché molti progetti closed-source non sono documentati bene?

Perché (1) scrivere una buona documentazione e (2) mantenerla costa unenorme quantità di denaro.

  1. Limmediato il costo (costo della stesura della documentazione) è chiaramente visibile agli stakeholder: se il tuo team chiede di trascorrere i prossimi due mesi a documentare il progetto, sono due mesi aggiuntivi di stipendio da pagare.

  2. Lo Il costo a termine (costo di mantenimento della documentazione) diventa abbastanza facile anche per i manager, ed è spesso il primo obiettivo quando devono abbassare il costo o abbreviare 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 non dover sprecare qualche giorno a esplorare il codice legacy solo per capire una cosa fondamentale che avrebbe dovuto essere documentata anni fa) sono, daltra parte, difficili da misurare, il che conferma la sensazione di alcuni manager che scrivere e mantenere la documentazione sia una perdita di tempo.

Quello che spesso osservo è che:

  1. Allinizio, il team è disposto a documentare molto.

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

  3. Pochi mesi in seguito, una nuova persona che si unisce al progetto praticamente non può utilizzare la documentazione, perché non corrisponde affatto al sistema attuale.

  4. Notando che, la direzione incolpa gli sviluppatori per non mantenere la documentazione; gli sviluppatori chiedono di dedicare qualche settimana allaggiornamento.

    • Se la direzione concede alcune settimane per questo, il ciclo si ripete.

    • Se la direzione rifiuta, sulla base dellesperienza 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. Trascorri 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, a fare refactoring regolare, a utilizzare modelli di progettazione o ad aggiungere un numero sufficiente di unit test.

  • Dare lesempio. Se scrivi una buona documentazione, anche le tue coppie potrebbero iniziare a farlo.

  • Esegui revisioni sistematiche del codice, comprese revisioni formali del codice mirate allispezione della documentazione.

  • Se alcuni membri del team sono particolarmente antipatici a una buona documentazione (o affatto documentazione), discuti largomento con loro in privato, per capire quali sono gli impedimenti che impediscono loro di scrivere una documentazione migliore. Se danno la colpa alla mancanza di tempo, vedi lorigine dei problemi.

  • Rendi misurabile la presenza o la mancanza di documentazione per alcune settimane o mesi, ma non concentrati 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 dei punteggi bassi.

  • Usa la gamification. Questo si unisce al punto precedente.

  • Usa rinforzo positivo / negativo.

  • (Vedi il commento di SJuan76 ) Considera la mancanza di commenti come errori. Ad esempio, in Visual Studio, puoi selezionare unopzione per generare la documentazione XML. Se controlli anche che tutti gli avvisi siano trattati come errori, la mancanza di un commento allinizio di una classe o di un metodo interromperà la compilazione.

    Come per i tre punti precedenti, questo dovrebbe essere usato con cautela. Lho usato per un po con un team particolarmente duro di programmatori principianti, e alla fine è arrivato con commenti conformi a StyleCop come questo: 

  /// <summary> /// Gets or sets the PrimaryHandling. /// </summary> public Workflow PrimaryHandling { get; set; }

che, hm …, non sono stati particolarmente utili.

Ricorda: niente di automatizzato può aiutarti a individuare commenti negativi quando i programmatori vogliono fregarti . Solo codice revisioni e altre attività umane aiuteranno.

Esistono buoni esempi di quando è necessaria una documentazione minima o nulla?

La documentazione che spiega larchitettura e il design non è necessaria:

  • Per un prototipo,

  • Per un progetto personale scritto in poche ore per portare a termine un compito, pur essendo abbastanza sicuro che questo progetto non verrà più mantenuto,

  • Per qualsiasi progetto in cui è ovvio, dato il di piccole dimensioni, insieme al codice particolarmente pulito, che impiegherai più tempo a scrivere documentazione rispetto a tutti i futuri manutentori ad esplorare il codice.

La documentazione in-code (commenti sul codice) non è necessaria secondo alcuni sviluppatori quando il codice è auto-documentante. Per loro, la presenza di commenti, tranne in rari casi, non è un buon segno, ma un segno che il codice non è stato “t riformattato 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.

Commenti

  • A ‘ come incoraggiare ‘, aggiungerei che molti IDE consentono la notifica della documentazione mancante come avvertenze. In alternativa, forse unanalisi statica della documentazione può essere eseguita presso lOSB (ovviamente, questo da solo non sarebbe sufficiente).
  • @ SJuan76: Infatti. Visual Studio può anche trattare la mancanza di commenti come un errore in fase di compilazione. Ho modificato la mia risposta per aggiungere una nota a riguardo.
  • @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, ovvero la definizione di altre storie di fatto, non devono includere il completamento delle storie di documentazione. Come suona?
  • @ArseniMourzenko – ‘ vorrei aggiungere altri due punti alla tua risposta. (1) In Jira ecc., Aggiungi sempre unattività per la documentazione. (2) Fai esaminare i documenti da altre 2 persone & inserendo anche questo come compito. In questo modo, verrà ricordato alle persone di documentare & evitando di scrivere documenti di bassa qualità (a causa della revisione). Se ‘ non gli dai la priorità & la rivedi, allora diventerà cattivo. So che Amazon esegue molti documenti & revisioni di documenti, forse un po troppi.

Risposta

Penso che dovresti fare una distinzione tra commenti e documentazione. Sebbene i commenti siano descrittivi, mancano di coerenza, sono sparsi in tutto il codice. I commenti non dovrebbero mai compensare il codice che non è abbastanza autodescrittivo, invece dovrebbe suggerire agli altri programmatori parti difficili.

Se il codice debba essere documentato dipende dalla scala del progetto. Sicuramente ci sono persone che credono che tutto debba essere documentato, e sembra facile giustificare quel pensiero perché chi oserebbe opporsi documentare la conoscenza? Fortunatamente lo sviluppo del software non è scienza e il mondo non crolla se i dettagli dietro il tuo programmino diventano oscuri. Ora, riguardo a un software professionale per molti sviluppatori, sì, ovviamente dovresti documentare il tuo codice. Ma se sei nella posizione per programmare a quel livello, allora lo sapresti ovviamente.

tl; dr

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

Commenti

  • Fortunately software development is not science Per favore dimmi di più sul motivo per cui ci credi.
  • @Borat – Lo sviluppo del software è una disciplina ingegneristica, il che implica che utilizza gli strumenti forniti dalla scienza.
  • Non sto chiedendo che tutto sia documentato. Dovrebbe essere quanto basta per fornire una panoramica di alto livello di ciò che fa un sistema e un codice. Ad esempio, dimmi come utilizzare la mia TV. Non ‘ mi interessa se utilizza LCD, CRT, Tubi per vuoto o dispositivi a stato solido per portare a termine il lavoro . Se un riparatore vuole queste informazioni, crea una documentazione separata per lui.
  • Se vuoi una panoramica di alto livello, i nomi degli identificatori sono sufficienti. Proprio come il pulsante sulla TV potrebbe avere unetichetta ” On “. Quindi stai chiedendo dettagli di basso livello.
  • @LeopoldAsperger: Penso che Borat stia parlando di documentare architettura e design, non metodi nelle classi.

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *