C'è qualche motivo logico per generare automaticamente la documentazione del codice? [chiuso]

La generazione automatica della documentazione può essere eseguita con una varietà di strumenti, tra cui GhostDoc è uno dei più importanti. Tuttavia, per definizione, tutto ciò che genera è ridondante. Dà un'occhiata a nomi di metodi, classi, ecc . E mostra l' inglese che potrebbe spiegarli in modo più dettagliato. Nel migliore dei casi, fa ciò che il lettore potrebbe già fare nella loro testa (esempi presi da qui ):

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

Nel peggiore dei casi, può effettivamente generare una bizzarra documentazione che in realtà è fuorviante nel suo tentativo di capire euristicamente il significato dei nomi:

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

Sembra che l'atteggiamento con GhostDoc sia "intrinsecamente migliore avere una sorta di documentazione XML formale", ma quando tale documentazione è ridondante al 100%, perché? Non sta semplicemente sprecando un sacco di spazio nella migliore delle ipotesi?

Nel mio posto di lavoro, dobbiamo documentare tutto, e quasi sempre con i documenti generati automaticamente di GhostDoc. Lo fai, e ci sono ragioni razionali per non lasciare semplicemente il codice senza documenti se non hai intenzione di scrivere la documentazione da solo?

[...] documenta tutto, e quasi sempre con i documenti generati automaticamente di GhostDoc. Lo fai, e ci sono ragioni razionali per non lasciare semplicemente il codice senza documenti se non hai intenzione di scrivere la documentazione da solo?

No. La documentazione generata da GhostDoc è boilerplate (simile a come la creazione di una nuova classe OO in un IDE crea la boileplate per una classe con un costruttore o qualcosa del genere). La parte utile della documentazione è ciò che seguirà dopo l'aggiunta del boilerplate.

Mentre si deve documentare tutto sul posto di lavoro, sembra tuoi coleagues trovato il modo perfetto intorno ad esso: solo finta.

In un linguaggio tipicamente statico, la documentazione in stile Javadoc non è per gli autori, ma per i consumatori. L'autogenerazione rende semplicemente più semplice per gli autori conservare la documentazione per il consumo da parte di altre persone.

Se stai usando un linguaggio tipicamente statico e non stai scrivendo una libreria per il consumo di terze parti, l'autogenerazione non ti compra molto, e nella mia esperienza è usata raramente. Se stai usando un linguaggio tipizzato in modo dinamico, la documentazione in stile javadoc viene spesso utilizzata per documentare i tipi, anche solo per uso interno, ma l'autogenerazione non conosce i tipi, quindi tutto ciò che ti salva è evitare la copia manuale della piastra della caldaia.

Ad ogni modo, non pensare all'autogenerazione come alla produzione di un prodotto finito. Pensa a come produrre la piastra della caldaia per te, quindi tutte le modifiche apportate manualmente sono significative.

C'è qualche motivo logico per generare automaticamente la documentazione del codice?

Da quale prospettiva?

Se gestissi la compagnia o il gruppo di sviluppo, allora non ci sono buone ragioni. Sono fermamente nel campo "commenti dovrebbero spiegare perché ". Costringere le persone a commentare classi / funzioni / proprietà è peggio che senza valore, poiché non sono aggiornati, fuorviano il lettore, sono usati come scusa per non rendere il codice leggibile e così via. Questi commenti fanno perdere tempo sia a scriverli, a leggere il codice, sia ai bug causati da essi. Alcuni sosterranno che i documenti API in stile JavaDoc sono un motivo per commentare, ma anche in base a tale argomento una piccola parte del codice dovrebbe far parte dell'API pubblica e JavaDoc non è un sostituto per i documenti API reali.

Come sviluppatore, ho lavorato in alcuni posti che richiedono commenti in questi luoghi, nonostante la mia opinione. Dal momento che non ho il tempo o la pazienza di scrivere un mucchio di cazzate che nessuno userà, lo faccio invece con GhostDoc. Questo mi permette di passare quel tempo a fare cose importanti. Molto più efficiente del cambiamento della politica aziendale.

Un'altra cosa positiva che ho scoperto usando GhostDoc è che serve a verificare che i miei nomi siano buoni. Se GhostDoc non è in grado di generare una documentazione decente per una funzione, è un odore che i nomi delle mie funzioni o dei parametri possano essere scadenti. Anche se non userei lo strumento solo per questo, è un piccolo effetto collaterale se mi viene comunque fatto perdere tempo.

EDIT : ho frainteso la domanda originale; Anche se credo che la generazione di documentazione (cioè non di codice documenti ) può essere estremamente utile (vedi risposta originale per quanto riguarda Doxygen sotto), auto-generare commenti (che è qualcosa che in realtà fa GhostDoc) sembra folle per me. Non riesco a capire perché qualcuno si aspetterebbe che un programma sia in grado di leggere il codice sorgente non commentato e scrivere commenti che lo chiariranno davvero.

È ipotizzabile che un'utilità di generazione di commenti estremamente "intelligente" possa essere programmata per riconoscere determinati schemi e generare commenti in stile "come"; per esempio, potrebbe riconoscere l'algoritmo di calcolo della varianza di Knuth e fornire un commento che spieghi come funziona e perché l'algoritmo ingenuo non sarebbe appropriato. Forse una tale utilità potrebbe anche essere programmata per riconoscere modelli di progettazione canonici orientati agli oggetti (ad es. Fabbrica astratta) e inserire commenti che indicano quale modello viene utilizzato e quali classi stanno giocando in quali ruoli.

Ma a mio avviso, i commenti più utili non spiegano "come" qualcosa funziona, poiché il codice stesso dovrebbe mostrarlo, ma " perché " commenta, spiegando "perché" una cosa particolare viene fatta. Come notato da David Hammen nei commenti qui sotto, per generare commenti "perché", un'utilità dovrebbe "leggere la mente del programmatore". Ovviamente questo è impossibile.

Sulla base degli esempi forniti, tuttavia, sembra che GhostDoc non compia nemmeno il compito di creare veri commenti in stile "how". Così è, a mio parere, peggio che inutile, dal momento che ciò che non genera può essere inane e fuorvianti (come nel secondo esempio).

Risposta originale: perché l' estrazione e la formattazione automatiche della documentazione è una buona idea

Il mio team di software utilizza Doxygen. La ragione principale di ciò è che abbiamo bisogno di documentazione non di codice sorgente (cioè leggibile da non programmatori) delle caratteristiche del codice / comportamento / ecc., Ma riteniamo che sia una pratica migliore integrarla nel codice sorgente stesso piuttosto che mantenerlo come secondo documento . Questo ci aiuta a mantenere la documentazione sincronizzata con il codice sorgente (anche se ovviamente non può mai essere completamente garantito, molto meno automatizzato) e minimizza il sovraccarico di scrivere documentazione (poiché la documentazione per un pezzo di codice può essere banalmente incorporata nel file contenente il codice stesso).

Quindi l'obiettivo del nostro uso di Doxygen non è quello di estrarre informazioni dal codice stesso, ma di mantenere la documentazione del codice sorgente il più vicino possibile al codice sorgente stesso.

Questo ci consente anche di utilizzare un singolo strumento per creare sia una "teoria delle operazioni" che descriva la nostra intera base di codice sia diversi set di "note di rilascio" che descrivono il prodotto software, ma in realtà non contengono alcuna "documentazione del codice" nel senso tipico.

Per quanto riguarda il motivo per cui avremmo bisogno di una documentazione non di codice sorgente del comportamento del nostro codice, ci sono due motivi:

• Il nostro prodotto non è semplicemente un software; è uno strumento complesso che integra molti componenti hardware, tra cui alcuni laser di fantasia e fluidica. Abbiamo bisogno di ingegneri senza molto sfondo software per avere una buona comprensione di esattamente come le parti interne del nostro si comportano codice, e dicendo loro "leggere il codice sorgente" non sta per raggiungere questo obiettivo.
• Dobbiamo seguire alcune norme di qualità, alcune imposte internamente dall'azienda e altre legalmente imposte dal governo federale. Sebbene il processo di qualità sia (o almeno possa essere) estremamente prezioso e utile, comporta una quantità non trascurabile di costi generali, parte del quale è compito del team del software fornire questo tipo di documentazione dettagliata del software. Ancora una volta, l'integrazione di questa documentazione con il codice stesso riduce al minimo le spese generali e ci aiuta a mantenere la documentazione aggiornata.

Si noti che il secondo punto elenco è abbastanza simile al punto che un paio di altre risposte hanno fatto riguardo ai manager che vogliono rassicurare (/ vantarsi dei diritti) di sapere che esiste una documentazione (indipendentemente dalla qualità) per ogni pezzo di codice sorgente; quel modo di inquadrarlo, tuttavia, ignora il fatto che la documentazione con mandato esterno può effettivamente avere alcuni vantaggi legittimi.

Certamente, la documentazione automatizzata è particolarmente utile quando può riprodurre descrizioni approfondite e appropriate scritte dagli autori del codice. Altrimenti, è solo un formattatore automatico glorificato.

Ma la formattazione non è inutile. È utile riuscire a trovare i metodi pubblici di una componente di grandi dimensioni in un solo sguardo, ordinati e garantiti come completi. Se hai bisogno di un frobnickmutatore e non è lì, sai che non è lì senza guadare il codice sorgente. (Anche i risultati negativi hanno valore: sai che devi fare qualcosa e hai più tempo per farlo perché non devi guadare.)

Quindi, sì, la generazione automatica di documenti aggiunge un certo valore. Certamente non tanto quanto i manager probabilmente credono, e di solito nemmeno quanto un buon editor di copie farebbe, ma niente di niente.

In questa forma è peggio che inutile, ma solo perché si basa solo sulla firma pubblica (che, nel caso di Javadoc, è comunque visibile a chiunque legga il documento API).

Ma è possibile scrivere strumenti di documentazione automatizzata che considerano anche il corpo del metodo. Come prova del concetto ho scritto un piccolo plug-in Eclipse che aggiunge un elenco di altri metodi chiamati dal metodo documentato a Javadoc. (Non tutte le chiamate ovviamente, puoi definire i filtri, ad esempio per pacchetto.)

E in realtà l'ho trovato abbastanza utile quando si tracciava mentalmente una base di codice completamente sconosciuta. Certo, è un caso d'uso molto limitato ma è stato sicuramente di aiuto.

Sulla base di quell'esperienza, la risposta alla domanda è: sì, ma abbiamo bisogno di strumenti molto più intelligenti.

Aggiornamento: ovviamente una domanda aggiuntiva (che dovrebbe essere posta prima di scrivere qualsiasi tipo di documentazione) è chi sia il target di riferimento. Se stiamo documentando un'API pubblica per i client di quell'API, l'aggiunta di tutti questi dettagli di implementazione è un no-no dato che qualsiasi cosa tu abbia inserito in Javadoc è tecnicamente parte dell'API.

Ma se il pubblico target è costituito da altri sviluppatori che lavorano sullo stesso prodotto, l'aggiunta automatica di informazioni sui dettagli di implementazione, ad esempio quali metodi modificano o leggono un determinato campo, è accettabile e abbastanza utile.

Non conosco altri ambienti, ma quando si tratta di grandi progetti PHP (spesso open source) che altri hanno scritto, phpXRef è un vero salvavita (specialmente se il documento viene messo online e Google può indicizzarlo).

Anche un progetto mal commentato può almeno aiutarmi a rintracciare dove sono state definite le cose e dove vengono utilizzate (ad esempio durante il refactoring).

Se ben commentate, le pagine risultanti si avvicinano a una Bibbia perfetta per la base di codice (per i miei usi comunque).

Inoltre, il mio IDE preferito genererà automaticamente il blocco di commenti (se digito / **) che esegue circa il 75% del lavoro di commento per me. È incredibile quante cose stupide mi hanno impedito di commettere durante la mia vita da programmatore solo perché ho dovuto spiegare ad altre persone (e futuro me) cosa sto facendo. Quando il mio commento per il generatore di documenti è più grande del metodo, questo di solito significa che non ho avuto abbastanza caffè e potrei voler pensare un po 'di più.

Questi stessi blocchi di commenti creano anche il testo di "aiuto" di completamento in linea in modo che io possa vedere esattamente cosa ci si aspettava (dagli altri programmatori) mentre scrivo la chiamata di funzione. Questo è un enorme aumento della produttività per me (specialmente in quei rari casi limite in cui qualche altro utile sviluppatore ha scritto "per l'amor del cielo do / do-not X" - che può risparmiare molto dolore.

Non posso sottolineare abbastanza quanto sia utile avere i tipi di input previsti specificati in progetti PHP complessi (e spesso mal nominati) e l'ordine degli argomenti in metodi usati meno frequentemente. Anche con il mio codice, non riesco sempre a ricordare quali argomenti ho specificato per qualcosa che non ho toccato in un'epoca.

In un caso significava che la fonte dei problemi ricorrenti era che, per qualche motivo che si rifletteva male sugli sviluppatori precedenti, alcune funzioni e persino costanti erano definite in un numero enorme di posti (con un certo grado di incoerenza per aggiungere "divertimento") . Questo era il segno di allontanarsi dal progetto.

Nei progetti più grandi avviati prima dell'adesione, posso vedere quale sviluppatore (supponendo che abbiano taggato il file di classe con un nome e un'e-mail) ha creato la classe e semplicemente essere in grado di trovare e parlare con lo sviluppatore giusto è estremamente utile.

Elenchi di attività automatiche: l'utilizzo del tag @todo (comune nel tipo di progetti in cui mi trovo a lavorare) significa che la documentazione può tenere traccia delle cose che richiedono un po 'più di lavoro (o funzioni che sono riconosciute mancanti). Ancora una volta il mio IDE tiene traccia di questo e che da solo funge da buona guida su ciò che richiede prima la mia attenzione.

Infine (e molto importante per me) rimuove il sovraccarico non banale di scrivere tutto questo e quindi cercare di tenerlo aggiornato quando alcuni (leggi molti) programmatori commettono modifiche e non parlano con i manutentori della documentazione.

Quindi, i motivi includono:

• Risparmiare agli sviluppatori successivi un sacco di tempo,
• Tenere traccia di dove vengono chiamate (e definite) le funzioni,
• Individuazione di codici stupidi,
• Trovare (come un altro ha sottolineato) quando manca qualcosa,
• Semplificazione del refactoring (mai molto divertente)
• (In molti casi) avere un'idea di ciò che lo sviluppatore stava cercando di fare (supponendo che avesse lasciato delle note).
• Se il progetto è abbastanza complesso da avere più licenze in corso (non è divertente) posso vedere rapidamente quali licenze si applicano a una determinata sezione. Certo, questo è un bonus laterale.
• Avere un'idea di con chi parlare di un file di progetto.
• Elenchi di attività automatiche

Inoltre, non sottovalutare il valore di rendere felici i boss con i capelli a punta con il semplice tocco di un pulsante.

In breve, i "commenti sulla documentazione automatica" sono fondamentali per le mie abitudini di programmazione. Sono sicuro che ci sono molti che pensano che sia zoppo, ma sono anche altrettanto sicuro che ci sono poche persone che sanno esattamente cosa sto dicendo. Non so come sono sopravvissuto prima di scoprire phpXRef (e il mio IDE preferito).

Spesso è utile utilizzare generatori di documentazione per creare commenti o "stand-in" che vengono successivamente rivisti dagli sviluppatori reali. Uso spesso la funzione auto-JavaDoc di Eclipse per generare il commento dell'intestazione con tipi di parametri e valori di ritorno già inseriti, quindi aggiungo semplicemente la "carne" della documentazione.

Come sviluppatore C # uso Stylecop, che richiede commenti per tutte le classi, metodi, ecc. Genero automaticamente questi commenti usando uno strumento. Il più delle volte, i commenti generati dallo strumento sono sufficienti e potrebbero essere dedotti dal nome dell'oggetto, ad esempio una classe Person e campo ID.

Ma SE voglio commentare ulteriormente un metodo non ovvio, è molto facile espandere la documentazione della piastra di cottura e alcune spiegazioni su ciò che fa. Ad esempio: ho un metodo sulla mia classe Person, che restituisce FirstName + Lastname, ma ho aggiunto un po 'di docu su cosa sta succedendo quando manca uno di entrambi.

In breve: penso che il docu plateplate possa essere dannoso se non si modifica mai il testo fornito dal generatore. In tal caso, è solo il rumore di linea. Ma se li vedi come modello, abbassano la barra per fornire commenti utili e utili a te o ai tuoi consumatori. Potresti scrivere i commenti senza generarli automaticamente? Certo, ma dovresti rispettare il formato (che nel caso C # è piuttosto dettagliato e fastidioso da generare a mano) e ciò riduce la possibilità che tu fornisca davvero questo commento ad al ..

Evita la tautologia

L'unica volta che dovresti avere bisogno di qualsiasi tipo di documentazione per il codice è spiegare perché un metodo / funzione sta facendo qualcosa, il nome dovrebbe essere sufficiente per quello che sta facendo.

Se stai facendo qualcosa che non è idiomatico o viola il principio del minimo stupore , è necessaria la documentazione.

La documentazione generata automaticamente che è solo un formattatore per la produzione di informazioni è quasi richiesta dai consumatori del codice. Javadoc lo fa estremamente bene.

Non tutto dovrebbe essere documentato manualmente

Cose come i metodi getXXX / setXXX dovrebbero essere autoesplicativi, quindi la documentazione generata automaticamente che ti fa sapere che esistono verrà ben accolta.

La documentazione del codice, almeno del tipo "automatico", rappresenta il minimo comune denominatore per le persone che cercano di capire l'applicazione.

Gli utenti più sofisticati non apprezzerebbero la documentazione automatica del codice. Avrebbero preferito piuttosto una documentazione "mirata" che dicesse loro cosa (poco) avevano bisogno di dire.

Gli utenti meno sofisticati non lo apprezzerebbero per il motivo opposto; non lo capiranno comunque.

Gli utenti più "riconoscenti" della documentazione automatica del codice sono quelli per i quali "una piccola conoscenza" è una cosa pericolosa. "Potrebbero o meno comprendere la documentazione (anche se è probabile che lo facciano), ma si sentiranno bene con" essere ". Questo pubblico include la maggior parte dei tipi" gestionali ". Se questo è il tuo pubblico principale, la documentazione automatica del codice potrebbe essere una buona cosa.

alla semplice risposta a "perché generare documenti" si può semplicemente rispondere mostrando MSDN.

Immagina di provare a scrivere un programma che utilizza una libreria in cui non esiste documentazione API. Sarebbe un incubo. MSDN è un ottimo esempio del tipo di documento che può essere generato dal codice sorgente e dai commenti e costituisce una risorsa essenziale per gli sviluppatori.

Se stai scrivendo un'applicazione (cioè non una libreria che può essere consumata da altri), allora forse c'è un caso per non preoccuparti - ma anche allora, quanto di un'applicazione di grandi dimensioni, solo interna, non contiene un mucchio di librerie Comunque? Quando ti unisci a un team del genere, avere alcuni documenti API consultabili sarà utile.

Nessuno strumento scriverà la tua documentazione per te, ma ti danno la piastra di caldaia che dovresti comunque scrivere manualmente, alcuni strumenti (come doxygen) genereranno anche diagrammi ed elenchi di riferimenti (ad esempio di funzioni chiamate e chiamate ) che non sarebbero facilmente individuabili nemmeno guardando il codice sorgente.

Ovviamente il buon senso pragmatico dovrebbe essere applicato a ciò che viene documentato, le proprietà e le funzioni minori possono essere ignorate (e saltate dalla generazione anche negli strumenti), ma in nessun momento qualcuno dovrebbe dire "c'è il codice sorgente, è abbastanza documentazione" in qualsiasi momento .