Quanto documentazione tecnica (per sviluppatori futuri) è sufficiente ? Esiste un rapporto tra la codifica delle ore e la documentazione delle ore appropriata?
Papadimoulis sostiene che dovresti
produce the least amount of documentation needed to facilitate the most understanding,
È una buona guida o ci sono cose specifiche che dovrei creare?
Che ne dici di alcuni test di usabilità del corridoio? Mostra il codice e la documentazione a uno sviluppatore che non ha familiarità con il progetto. Quando riesci a farlo senza l'opprimente necessità di spiegare qualcosa mentre li guardi rivedere il codice, ne hai abbastanza.
La perfezione non è più un successo in più, ma è più un buon ritorno per il mondo.
Antoine de Saint-Exupéry
Ho riflettuto su questo argomento per un po '.
La mia conclusione è che non si tratta di quantità, ma di qualità e contesto.
Ad esempio, una struttura di progetto corretta supera i commenti che spiegano dove si trovano i file (implementazione vs. intensione)
Analogamente, la classificazione per chiarire il contesto batte il nome (Id su un paziente - > Patient.Id).
Credo che il DDD abbia voce in capitolo in una buona documentazione: la classificazione fornisce contesto, il contesto crea confini e confini che portano a implementazioni intenzionali (questo è il posto in cui questo appartiene, piuttosto che deve esistere).
Il codice in sé non è abbastanza buono da essere considerato documentazione. Il problema nella maggior parte dei casi non risiede nel fatto che il funzionamento dei codici è commentato o non commentato, ma piuttosto la forza trainante (logica di dominio) non lo è.
A volte dimentichiamo chi è il capo - se il codice cambia, la logica del dominio o il ragionamento non dovrebbero, ma se la logica o il ragionamento del dominio cambia il codice sicuramente lo farà.
La coerenza è molto importante anche - la convenzione da sola è inutile se non è coerente.
I modelli di progettazione non sono solo "buone pratiche" - è un gergo che noi sviluppatori dovremmo capire. Dire a uno sviluppatore di aggiungere un nuovo tipo a una fabbrica è meglio compreso piuttosto che aggiungere un nuovo tipo a un metodo (dove il contesto e la coerenza sono deboli o mancanti).
La metà della lotta è familiarità .
Da una nota a margine, le API che sembrano favorire molta documentazione sono anche molto sensibili al contesto e al dominio. A volte la duplicazione della funzionalità non è malvagia (stessa cosa, contesti diversi) e dovrebbe essere considerata separata.
In termini di commenti, è sempre opportuno sottolineare la logica del dominio dietro al ragionamento.
Ad esempio, lavori nel settore medico. Nel tuo metodo scrivi "IsPatientSecure = true;"
Ora, qualsiasi programmatore decente può capire che il paziente viene contrassegnato come sicuro. Ma perché? Quali sono le implicazioni?
In questo caso il paziente è un detenuto che è stato trasferito in modo sicuro in un ospedale fuori sede. Sapendo questo, è più facile immaginare gli eventi che portano fino a questo punto (e forse ciò che deve ancora accadere).
Forse questo post sembra filosofico al meglio - ma ricorda che è "ragionamento" o "logica" di cui stai scrivendo - non il codice.
Sono d'accordo con la citazione di Papadimouslis. Il codice sorgente può parlare da solo, ma il codice non può dirti perché esiste, come dovrebbe essere usato e come dovrebbe comportarsi il codice.
Non conosco un buon rapporto.
Ho ereditato centinaia di righe di codice con pochissima documentazione. È diventato difficile per me capire perché il codice è stato scritto. Dopo aver scoperto perché il codice è stato scritto, ho dovuto capire come usare il codice. Dopo averlo scoperto, ho dovuto capire come deve comportarsi in modo da poter supportare e mantenere il codice.
Proprio per esperienza, non rendere i commenti troppo specifici o finirai per dover mantenere il codice effettivo E la documentazione. È un incubo quando la documentazione e il codice non sono sincronizzati.
Abbastanza per farti smettere di pensare a te stesso.
Se in qualsiasi momento durante il tuo lavoro sei tipo "hmm forse dovrei documentarlo", vai avanti e fallo. Quindi, se hai scritto della documentazione e sei tipo "forse dovrei spiegarlo di più", vai avanti e fallo.
Risciacqua-ripeti fino a quando quella sensazione scompare.
Ho scoperto che un approccio orientato al rischio come quello presentato nel libro di George Fairbanks Just Enough Software Architecture funziona molto bene per capire quanta documentazione è sufficiente. Puoi leggere la sezione che presenta questo concetto (capitolo 3) sul suo sito web, ma l'idea principale è:
Per aiutare a calibrare le preoccupazioni in modo da poter dare la priorità ai rischi, ho trovato utile identificare un paio di obiettivi noti come Soglia di successo , ovvero la serie minima di obiettivi che la tua squadra ritiene che un progetto" di successo "debba raggiungere. Dal punto di vista della documentazione un esempio di ToS potrebbe essere qualcosa come "Uno sviluppatore dovrebbe essere in grado di costruire un semplice plug-in entro 4 ore dalla raccolta del framework per la prima volta."
Ora identifica alcuni rischi. Con il sistema che hai costruito (o stai costruendo) quali sono le cose che preoccupano maggiormente la tua squadra? Frasi come dichiarazioni di rischio. Mi piace lo stile condizionale delle conseguenze del SEI, ma ce ne sono altri. Esempi:
Ora come squadra, dai priorità ai rischi. Il voto plurimo funziona molto bene.
Attenua i rischi prioritari e ripeti l'inizio con l'identificazione finché il rischio di fallimento del progetto (definito dalla Soglia di successo) è entro un limite tollerabile. Generalmente questo significa che avrai dei rischi che la squadra è d'accordo non è una grande preoccupazione. Tieni presente che probabilmente non vorrai mitigare tutti i rischi. Un esempio di strategia di mitigazione per l'ultimo rischio di cui sopra potrebbe essere quello di creare un tutorial.
As little as possible, but as much as is necessary
Non ricordo dove e amp; quando l'ho sentito per la prima volta, ma è una massima con molte applicazioni.
Più complessa è la tecnologia o l'applicazione, più la documentazione sarà necessaria (ovviamente), ma chiaramente non vuoi perdere tempo a esagerare.
Il "test di corridoio" di JohnFx è valido. Ma fidati di te stesso; hai sviluppato il codice, e così tu, tra tutte le persone, dovresti avere un'idea degli elementi che richiedono un'attenzione in più, e degli elementi che saranno evidenti a tutti. Pensa alle difficoltà che hai sviluppato nel codice e probabilmente avrai un'idea di ciò che un altro sviluppatore vedrà quando guarderà il tuo codice.
Dimentica qualsiasi rapporto tra lo sforzo dedicato alla codifica e lo sforzo dedicato alla documentazione.
Credo che non si possa mettere questo in regole esatte. La ragione per documentare è di fornire le conoscenze non facilmente raccolte dal codice grezzo in una forma in modo che altri possano capire e forse anche mantenere detto codice non elaborato.
Quindi l'unico modo in cui puoi dire se hai documentato abbastanza è chiedere al pubblico di destinazione se è abbastanza buono. Credo che il processo di "peer review" sia molto efficace in questo senso. Nota quanta spiegazione è necessaria per far capire al tuo pari di cosa stai parlando, e lavorare per minimizzarlo.
Se non lo hai mai fatto prima, non puoi stimare quanto lavoro ci vorrà, ma dopo alcune iterazioni otterrai un'idea molto migliore di quanto è necessario.
Leggi altre domande sui tag documentation