Quanta documentazione è sufficiente?

Quanta documentazione tecnica (per i futuri sviluppatori) è sufficiente ? C'è un rapporto tra la codifica delle ore e la documentazione delle ore che è appropriato?

Papadimoulis sostiene che dovresti

produrre la minima quantità di documentazione necessaria per facilitare la comprensione,

È una buona linea guida o ci sono cose specifiche che dovrei creare?

Che ne dici di alcuni test di usabilità in corridoio? Mostra il codice e la documentazione a uno sviluppatore che non ha familiarità con il progetto. Quando riesci a farlo senza un travolgente bisogno di spiegare qualcosa mentre li guardi rivedere il codice, ne hai abbastanza.

La perfezione è ora non pas quand il ny a plus rien à ajouter, mais quand il n'y a plus rien à retirer.
Antoine de Saint-Exupéry

Ho pensato a questo argomento per un po '.

La mia conclusione è: non è una questione di quantità, ma di qualità e contesto.

Ad esempio, una struttura del progetto corretta batte i commenti che spiegano dove si trovano i file (implementazione vs. intensione)

Allo stesso modo, la classificazione per chiarire il contesto batte la denominazione (Id on a Patient -> Patient.Id).

Credo che DDD abbia voce in capitolo in una buona documentazione: la classificazione fornisce contesto, il contesto crea confini e i confini conducono a implementazioni intenzionali (questo è il posto in cui appartiene, piuttosto che deve esistere).

Il codice in sé non è abbastanza buono per 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 del 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 del dominio o il ragionamento cambiano il codice lo farà sicuramente.

Anche la coerenza è molto importante: la convenzione di per sé è inutile se non è coerente.

I modelli di progettazione non sono solo "buone pratiche" - è un linguaggio che noi sviluppatori dovremmo capire. Dire a uno sviluppatore di aggiungere un nuovo tipo a una Factory è meglio inteso che aggiungere un nuovo tipo a un metodo (in cui il contesto e la coerenza sono deboli o mancanti).

Metà della lotta è familiarità .

Inoltre, le API che sembrano favorire molta documentazione sono anche molto sensibili al dominio e al contesto. A volte la duplicazione delle funzionalità non è malvagia (stessa cosa, contesti diversi) e dovrebbe essere trattata separatamente.

In termini di commenti, è sempre bene sottolineare la logica del dominio dietro il ragionamento.

Ad esempio, stai lavorando 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 trasferito in modo sicuro in un ospedale fuori sede. Sapendo questo, è più facile immaginare gli eventi che portano a questo punto (e forse ciò che deve ancora accadere).

Forse questo post sembra al massimo filosofico - ma ricorda che è il "ragionamento" o la "logica" di cui stai scrivendo - non il codice.

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

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 dovrebbe comportarsi in modo da poter supportare e mantenere il codice.

Solo per esperienza, non fare commenti troppo specifici o finirai per mantenere il codice effettivo E la documentazione. È un incubo quando la documentazione e il codice non sono sincronizzati.

Abbastanza per farti smettere di indovinare secondo 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 ti piace "forse dovrei spiegarlo di più", vai avanti e fallo.

Risciacqua-ripeti finché quella sensazione non scompare.

Ho scoperto che un approccio orientato al rischio come quello presentato nel libro Just Enough Software Architecture di George Fairbanks funziona estremamente bene per capire quanta documentazione è sufficiente. Puoi leggere la sezione che presenta questo concetto (capitolo 3) sul suo sito web ma l'idea principale è:

• Esprimi le cose che ti preoccupano della "comprensione del sistema" come rischi
• Dai la priorità ai rischi
• Riduci i rischi fino a quando il tuo team ritiene che il rischio del progetto non sia stato sufficientemente ridotto. In questo caso probabilmente creerai un tipo di documentazione.

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 l'insieme minimo di obiettivi che la tua squadra pensa che un progetto "di successo" debba raggiungere. Dal punto di vista della documentazione, un ToS di esempio potrebbe essere qualcosa del tipo "Uno sviluppatore dovrebbe essere in grado di creare un plug-in semplice entro 4 ore dalla raccolta del framework per la prima volta".

Ora identifica alcuni rischi. Con il sistema che hai creato (o stai costruendo) quali sono le cose che preoccupano maggiormente la tua squadra? Frase queste come dichiarazioni di rischio. Mi piace lo stile delle conseguenze-conseguenze del SEI ma ce ne sono altri. Esempi:

• Il modello di dati è ampio e complesso; gli sviluppatori potrebbero non sapere quali elementi di dati utilizzare in una determinata situazione.
• Il sistema ha limiti di connessione API per aumentare l'affidabilità; gli sviluppatori potrebbero accidentalmente superare il limite di connessione.
• I plug-in vengono utilizzati in diversi passaggi sequenziali; gli sviluppatori potrebbero non creare plug-in tenendo presenti questi passaggi ordinati.

Ora come squadra, dare la priorità ai rischi. Il voto multiplo funziona molto bene.

Riduci i rischi con priorità assoluta e ripeti a partire dall'identificazione fino a quando il rischio di fallimento del tuo progetto (definito dalla soglia di successo) rientra in un limite tollerabile. Generalmente questo significa che avrai alcuni rischi che il team concorda non è un grosso problema. Tieni presente che probabilmente non vorrai mitigare tutti i rischi. Una strategia di mitigazione di esempio per l'ultimo rischio sopra potrebbe essere quella di creare un tutorial.

Il meno possibile, ma quanto è necessario

Non riesco a ricordare dove e quando l'ho sentito per la prima volta, ma è un massimo con molte applicazioni.

Più complessa è la tecnologia o l'applicazione, maggiore sarà la documentazione (ovviamente), ma chiaramente non si vuole perdere tempo a esagerare.

Il "test di corridoio" di John FX è valido. Ma fidati di te stesso; hai sviluppato il codice, e quindi tu di tutte le persone dovresti avere un'idea degli elementi che necessitano di maggiore attenzione e degli elementi che saranno ovvi per tutti. Pensa alle difficoltà che hai avuto nello sviluppo del codice e probabilmente avrai un'idea di ciò che un altro sviluppatore vedrà quando guarderà il tuo codice.

Dimentica qualsiasi relazione tra lo sforzo dedicato alla codifica e lo sforzo speso a documentare.

Credo che non puoi metterlo in regole esatte. Il motivo della documentazione è quello di fornire le conoscenze non facilmente raccolte dal codice grezzo in una forma in modo che gli altri possano capire e forse persino mantenere detto codice grezzo.

Quindi l'unico modo per capire se hai documentato abbastanza è chiedere al pubblico di destinazione se è abbastanza buono. Credo che il processo di "peer review" sia molto efficace nel farlo in anticipo. Nota quanto è necessario spiegare per far capire al tuo collega ciò di cui stai parlando e lavorare per minimizzarlo.

Se non l'hai mai fatto prima, non puoi stimare quanto lavoro ci vorrà, ma dopo alcune iterazioni avrai un'idea molto migliore di quanto è necessario.