Perché dovresti documentare il codice? [duplicare]

Why should such a system be documented?

A mio parere, qualsiasi sistema che viene utilizzato in modo produttivo e che dovrebbe essere gestito da persone, dovrebbe avere la documentazione alla portata di quelle persone che sono responsabili per il suo supporto. La ragione è, semplicemente perché:

1. Non tutti gli sviluppatori hanno lo stesso QI: vuoi che tutti lo ottengano non solo con John.

2. Non tutto il codice è ovvio, gli algoritmi complessi non sono abbastanza leggibili da tutti.

3. Le regole aziendali, sebbene possano essere leggibili, potrebbero non solo mostrare il motivo per cui sono presenti. Prendi ad esempio questa linea in un'applicazione di reporting:

   if (lastname>="ZZ") then goto loop
   

   è piuttosto chiaro al lettore che cosa sta succedendo ma non a perché questo è il caso?

4. Scoprire i dettagli richiede molto tempo, è uno spreco di denaro aziendale.

5. La dipendenza tra parti del sistema potrebbe non essere sempre evidente. Soprattutto nei processi batch in cui ogni lavoro appare come un programma indipendente, ma la sequenza di esecuzione è un pacchetto che deve essere elaborato in base a determinate regole (come esecuzioni mensili, ecc.).

6. La documentazione dovrebbe aiutarti a capire i registri e se i risultati sono corretti o meno.

7. Quando capisci la funzione di ciascun componente, puoi rispondere alle domande di lavoro. Say Suzan chiama dalla contabilità e chiede perché ci mancano 5 assegni questo mese? Alcuni programmatori potrebbero rispondere, bene, ho eseguito il lavoro e non mi hanno dato alcun errore - Questo non può aiutare Suzan. Se sai quale parte del sistema esegue l'estrazione dei dati per l'elaborazione dei controlli e poi sai quali sono le regole aziendali applicate per qualificare un assegno da stampare, puoi fornire una risposta utile - Supponendo che non ci siano errori.

Ricordare che la documentazione va ben oltre i commenti inseriti nel codice. Includono ERD, documenti relativi ai requisiti aziendali, documenti di progettazione, ecc.

In breve: una buona documentazione offre agli sviluppatori il controllo necessario per mantenere un sistema.

Gli sviluppatori di quel sistema stanno solo cercando di proteggere il loro lavoro.

Se il codice è ben documentato e comprensibile, allora gli sviluppatori sono facilmente sostituibili. Ovviamente, se il codice è completamente privo di documentazione ed è indecifrabile tranne che per quelli addestrati nelle arti COBOL arcane, allora non è così facile per quegli sviluppatori essere rimossi e sostituiti.

Come hai detto, quegli sviluppatori ci sono stati per oltre un decennio. Probabilmente stanno facendo bene oltre $ 100K, probabilmente più vicini a $ 200K. Sono sicuro che i manager hanno la tentazione di sostituirli con gli sviluppatori junior direttamente dal college (o dagli sviluppatori off-shore) che realizzeranno da 1/2 a 1/3 dello stipendio.

Ovviamente dipende dalla complessità, ma in generale direi che la risposta è abbastanza semplice ... Sì! Dici che è un linguaggio simile a COBOL, quante persone conoscono questa lingua?

Se questo sviluppatore ha un attacco di cuore o diventa non disponibile, chi sarà in grado di spiegare quando qualcuno ha bisogno di nuove informazioni sul design?

Il tempo è denaro, per essere al passo e iniziare a fare qualcosa che fa profitto. È più veloce sfogliare la documentazione per capire come dovrebbero funzionare le cose prima di fare il codice.

Se hai bisogno di aiuto esterno, sarebbe più economico e più veloce se possono leggere la documentazione.

Ci sono altre cose che non puoi vedere guardando il codice stesso. Pensieri sull'espansione futura. Alcuni codici potrebbero sembrare davvero stupidi, ma sono progettati in modo da ottenere una funzione o un'espansione.

Se l'attività dell'azienda si basa su questo programma, vuoi veramente che sia documentato in modo da poter risolvere rapidamente i problemi se succede qualcosa (ad esempio se il progettista della chiave si incazza e lascia).

Tutti noi troviamo un dolore nella 'A' scrivere documentazione. Posso consigliare la documentazione generata automaticamente come Doxygen , un ottimo strumento gratuito che legge il tuo codice e disegna diagrammi delle chiamate e raccoglie i commenti in un file della Guida o un manuale HTML. Non so se può gestire il tuo linguaggio simile a Cobol, ma ci sono script e varianti che lo estendono per gestire più lingue.

Di solito abbiamo fatto un documento di design perduto prima di iniziare un progetto, quindi documentiamo con i commenti in stile Doxygen nel codice. E 'stato abbastanza efficace da far entrare rapidamente nuove persone ...

Non sono sicuro che sarei d'accordo sul fatto che i commenti / la documentazione non siano necessari in generale. Ho osservato, tuttavia, che nel tempo, mentre il mio team e io siamo migliorati nella scrittura del codice, siamo stati in grado di ridurre la quantità di commenti. Per esempio. Se un metodo è chiamato ProcessFile (), perché si desidera aggiungere un commento che afferma "Questa funzione elabora un file"?

Tuttavia, ci sono casi in cui i commenti possono essere estremamente utili. Ad esempio quando lo scopo di una particolare affermazione non è ovvio. Per prendere un esempio estremamente semplice (semplicistico?): Puoi implementare una divisione per due come spostamento a destra dei bit.

La quantità di commenti dipende probabilmente anche dal linguaggio di programmazione che si utilizza. Ad esempio, confrontare il codice assembler con il codice scritto in un linguaggio di livello superiore come Java o C #. Di nuovo, sospetto che qui ci sia uno spettro.

Sono d'accordo, tuttavia, che i commenti non possano essere considerati attendibili in generale. Il motivo è che, in particolare con il codice che ha una certa età, il codice potrebbe essere stato modificato mentre i commenti sono rimasti gli stessi. Codice e commenti non sono sincronizzati. Nel peggiore dei casi questo tipo di commento può portare a conclusioni sbagliate da parte dello sviluppatore. La mia raccomandazione sarebbe di essere sempre cauto nell'usare le informazioni contenute nei commenti.

In sintesi, penso che un buon codice richieda meno commenti e nel caso estremo potrebbe essere auto-esplicativo. Per passare a un codice migliore nella mia esperienza di sviluppo basato sui test (TDD), il design semplice e il refactoring senza pietà sono i migliori strumenti. Nessuno di questi strumenti, tuttavia, sostituisce il pensiero appropriato per fare scelte appropriate e ragionevoli.

Ci sono diversi aspetti di questa domanda.

C'è un problema con i commenti nel codice, è che introducono un sovraccarico sui programmatori di maintanence, in quanto quando cambiano il codice, devono anche modificare i commenti. Ora A volte i commenti sono nel codice che chiama una funzione / metodo su come si comporta quel metodo, così anche il programmatore di maintanence sa di questi commenti per aggiornarli? probabilmente no.

In questo caso, sembra che tutti gli altri programmatori esistenti trovino la lettura del codice più facile che fidarsi dei commenti non aggiornati.

È possibile che la difficoltà a capire il codice sia che la lingua di programmazione non è familiare? e i suoi commenti non sono necessari, ma il vero problema è la formazione, la pratica e l'esperienza in questo linguaggio di programmazione?