Esiste un motivo logico per generare automaticamente la documentazione del codice? [chiuso]

[...] document everything, and almost always with GhostDoc's auto-generated docs. Do you do this, and are there any rational reasons not to simply leave code undocumented if you aren't going to actually write the documentation yourself?

No. La documentazione generata da GhostDoc è boilerplate (simile a come la creazione di una nuova classe OO in un IDE crea il 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 devi documentare tutto sul tuo posto di lavoro, sembra che i tuoi colleghi abbiano trovato il modo perfetto per farlo: fai finta.

In un linguaggio tipizzato staticamente, la documentazione in stile Javadoc non è per gli autori, è per i consumatori. L'autogenerazione rende semplicemente più semplice per gli autori conservare la documentazione che le altre persone possono consumare.

Se stai usando un linguaggio tipizzato in modo 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 si utilizza un linguaggio tipizzato dinamicamente, 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 salva evita la copia manuale dello standard di stampa.

In ogni caso, non pensare all'autogenerazione come alla produzione di un prodotto finito. Pensa a ciò che produce il boilerplate per te, quindi qualsiasi modifica apportata manualmente è significativa.

Is there any logical reason to auto-generate code documentation?

Dalla prospettiva di chi?

Se gestivo la società o il gruppo di sviluppo, non c'è una buona ragione. Sono fermamente nel "commento dovrebbe spiegare il perché " campo. Costringere le persone a commentare classi / funzioni / proprietà è peggio che inutile, dato che non sono aggiornate, ingannano il lettore, sono usate come scusa per non rendere il codice leggibile e così via. Questi commenti perdono tempo sia a scriverli, a leggere il codice, sia a bug causati da loro. Alcuni sostengono che i documenti API in stile JavaDoc sono una ragione per fare il commento, ma anche sotto quell'argomento una piccola parte del codice dovrebbe essere parte dell'API pubblica e JavaDoc non è un sostituto per i documenti API effettivi.

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

Un'altra buona cosa che ho trovato usando GhostDoc è che serve come controllo che i miei nomi siano buoni. Se GhostDoc non è in grado di generare una documentazione decente per una funzione, è un odore che i miei nomi di funzioni o parametri potrebbero essere scadenti. Anche se non utilizzerei lo strumento per solo questo, è un piccolo effetto collaterale se mi viene fatto perdere del tempo comunque.

EDIT : ho frainteso la domanda originale; anche se penso che la generazione di documentazione (cioè non-code documenti ) possa essere estremamente preziosa (vedere la risposta originale riguardante Doxygen in basso), generare automaticamente commenti (che è qualcosa che GhostDoc effettivamente fa) suona matto per me. Non riesco a capire perché qualcuno si aspetterebbe che un programma sia in grado di leggere codice sorgente senza commenti e scrivere commenti che lo chiariscano veramente.

È concepibile che un'utilità di generazione di commenti estremamente "intelligente" potrebbe essere programmata per riconoscere determinati modelli e generare commenti in stile "come"; ad esempio, potrebbe riconoscere l'algoritmo di calcolo della varianza di Knuth e fornire un commento che spiega come funziona e perché l'algoritmo ingenuo non sarebbe appropriato Forse una tale utility potrebbe anche essere programmata per riconoscere i modelli canonici di progettazione orientata agli oggetti (ad esempio Abstract Factory) e inserire commenti che indicano quale pattern viene utilizzato e quali classi stanno giocando quali ruoli.

Ma a mio parere, i commenti più utili non spiegano "come" qualcosa funziona, dal momento che il codice stesso dovrebbe mostrare questo, ma " perché " commenti, spiegando "perché" una cosa particolare è stato fatto. Come notato da David Hammen nei commenti qui sotto, al fine di generare commenti sul "perché", un'utilità dovrebbe "leggere la mente del programmatore". Ovviamente questo è impossibile.

Sulla base degli esempi forniti, tuttavia, GhostDoc non riesce nemmeno a realizzare il vero compito di creare commenti in stile "how". Quindi, a mio parere, è peggio che inutile, dal momento che ciò che fa genera può essere sciocco e fuorviante (come nel secondo esempio).

Risposta originale: perché la documentazione automatica estrazione e formattazione è una buona idea

Il mio team di software utilizza Doxygen. La ragione principale di ciò è che abbiamo bisogno della documentazione codice non sorgente (cioè leggibile dai non programmatori) delle caratteristiche del codice / comportamento / etc, ma riteniamo che sia una pratica migliore per integrare questo nel codice sorgente stesso piuttosto che mantenerlo come un secondo documento . Questo ci aiuta a mantenere la documentazione in sincronia con il codice sorgente (anche se ovviamente non può essere completamente garantita, molto meno automatizzata) e minimizza il sovraccarico della documentazione scritta (poiché la documentazione per un pezzo di codice può essere banalmente incorporata nel file contenente il codice stesso).

Quindi il focus 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 permette anche di usare un singolo strumento per creare sia una "teoria delle operazioni" che descrive 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 di codice" "nel senso tipico.

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

• Il nostro prodotto non è solo software; è uno strumento complesso che integra molti componenti hardware, inclusi alcuni laser e fluidi di fantasia. Abbiamo bisogno di ingegneri senza molto background software per avere una buona comprensione di esattamente come si comportano gli interni del nostro codice, e dire loro "leggi il codice sorgente" non lo farà.
• Dobbiamo attenerci a un bel po 'di regolamenti di qualità, alcuni incaricati internamente dalla società e altri legalmente autorizzati dal governo federale. Sebbene il processo di qualità sia (o almeno possa essere) estremamente prezioso e utile, comporta una quantità non trascurabile di spese generali, parte delle quali è compito del team di software fornire questo tipo di documentazione dettagliata del software. Anche in questo caso, l'integrazione di questa documentazione con il codice stesso riduce al minimo il sovraccarico e ci aiuta a mantenere aggiornata la documentazione.

Si noti che il secondo punto elenco è abbastanza simile al punto che un paio di altre risposte hanno fatto sui manager che vogliono la rassicurazione (/ vantarsi) di sapere che esiste qualche documentazione (indipendentemente dalla qualità) per ogni pezzo di codice sorgente; questo modo di inquadrarlo, tuttavia, ignora il fatto che la documentazione con mandato esterno può in realtà avere alcuni legittimi vantaggi.

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

Ma la formattazione non è inutile. C'è un valore nell'essere in grado di trovare i metodi pubblici di un componente più grande a un solo sguardo, ordinati e garantiti per essere completi. Se hai bisogno di un% mutatore frobnick , e non c'è, conosci non è lì senza guado nel codice sorgente. (Anche i risultati negativi hanno un valore: sai che devi fare qualcosa, e hai più tempo per farlo perché non dovevi guadare.)

Quindi, sì, la generazione automatica di documenti aggiunge un valore . Sicuramente non tanto quanto i gestori presumono, e di solito nemmeno tanto quanto un buon editor di copia, ma non nulla.

Non conosco altri ambienti, ma quando si parla di progetti PHP di grandi dimensioni (spesso open source) che altre persone hanno scritto phpXRef è un salvataggio assoluto (specialmente se il documento è collocato 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 quando si esegue il refactoring).

Quando ben commentato le pagine risultanti si avvicinano ad una Bibbia perfetta per il codice base (per i miei usi comunque).

Inoltre, il mio IDE preferito genererà automaticamente il blocco dei commenti (se scrivo / **), che fa per me circa il 75% dei commenti. È incredibile quante cose stupide mi siano state interrotte dall'impegnarmi per tutta la vita del mio programmatore solo perché ho dovuto spiegare ad altre persone (e al 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 bevuto abbastanza caffè e potrei voler pensare un po 'di più.

Questi stessi blocchi di commento di commento creano anche il testo di "aiuto" di completamento in linea in modo da poter vedere esattamente cosa ci si aspettava dagli altri programmatori mentre sto scrivendo la chiamata di funzione. Questo è un enorme incremento di produttività per me (specialmente in quei rari casi estremi in cui qualche altro utile sviluppatore ha scritto "per l'amor di Dio do / do-not X" che può far risparmiare un sacco di dolore.

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

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

Quindi i motivi includono il salvataggio di una serie di sviluppatori successivi, tenendo traccia di dove vengono chiamate (e definite) le funzioni, individuando codifiche sciocche, trovando (come è stato sottolineato da altri) quando manca qualcosa, semplificando il refactoring (mai molto divertimento ) e in molti casi avere un'idea di ciò che lo sviluppatore stava cercando di fare (supponendo che lui o lei ha lasciato delle note).

Se il progetto è abbastanza complesso da consentire l'esecuzione di più licenze (non è divertente), riesco a vedere rapidamente quali licenze si applicano a una determinata sezione. Ammetto che questo è un bonus laterale.

Nei progetti più grandi che sono iniziati prima di entrare, posso vedere quale sviluppatore (supponendo che abbia taggato il file di classe con un nome e una e-mail) abbia creato la classe e sia semplicemente in grado di trovare e parlare con lo sviluppatore giusto è estremamente utile.

Elenchi di attività automatici - l'utilizzo del tag @todo (comune nel tipo di progetti in cui mi trovo a lavorare) indica che la documentazione può tenere traccia di cose che richiedono un po 'di lavoro in più (o funzionalità che sono state ritenute mancanti). Ancora una volta il mio IDE tiene traccia di questo e questo da solo costituisce una buona guida su ciò che ha bisogno della mia attenzione.

Inoltre, non sottovalutare il valore di mantenere felici i capi dai capelli a punta con il semplice tocco di un pulsante.

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

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

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

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

E in effetti l'ho trovato abbastanza utile quando ho mappato mentalmente un codice base completamente sconosciuto. Certo, è un caso d'uso molto limitato ma è stato sicuramente un aiuto.

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

Aggiornamento: Naturalmente un'ulteriore domanda (una che dovrebbe essere richiesta prima di scrivere qualsiasi tipo di documentazione) è chi è il pubblico di destinazione. Se stiamo documentando un'API pubblica per i client di tale API, l'aggiunta di tutti questi dettagli dell'implementazione è un grande no-no in quanto tutto ciò che inserisci in Javadoc è tecnicamente parte dell'API.

Tuttavia, se il pubblico di destinazione è rappresentato 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.

Spesso è bene usare i generatori di documentazione per creare commenti standard o "stand-in" che saranno successivamente revisionati 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à compilati, quindi aggiungere semplicemente la "carne" della documentazione.

Come sviluppatore C # uso Stylecop, che richiede commenti per tutte le classi, i metodi, ecc. Autogenero questi commenti usando uno strumento. Nella maggior parte dei casi, i commenti generati dallo strumento sono sufficienti e potrebbero essere desunti dal nome dell'oggetto, ad es. una classe Person e un campo ID.

Ma se voglio commentare un metodo non ovvio ulteriormente, è molto facile espandere la documentazione di boilerplate 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 accadendo quando manca uno di entrambi.

In breve: penso che il documento standard possa essere dannoso se non si modifica il testo fornito dal generatore. In quel caso, è solo rumore di linea. Ma se li vedi come modello, abbassano la barra per fornire commenti validi e utili per te o per i tuoi consumatori. Potresti scrivere i commenti senza autogenerarli? Certo, ma dovresti rispettare il formato (che nel caso C # è piuttosto prolisso e fastidioso da generare a mano) e questo riduce la possibilità che tu fornisca realmente questo commento ad ogni ..

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 cosa sta facendo .

Se stai facendo qualcosa che non è idiomatico, o viola il principio di minimo stupore quindi è richiesta la documentazione.

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

Non tutto dovrebbe essere documentato manualmente

Cose come i metodi getXXX / setXXX dovrebbero essere auto-esplicative, quindi la documentazione di auto-generazione che ti consente solo di sapere che esistono sarà ben accolta.

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

Gli utenti più sofisticati non apprezzerebbero la documentazione di codice automatica. Preferirebbero avere una documentazione "mirata" che indichi loro che (poco) hanno bisogno di sentirsi dire.

Gli utenti meno sofisticati non lo apprezzerebbero per la ragione opposta; non lo capirebbero comunque.

Gli utenti più "elogiativi" della documentazione automatica del codice sono quelli per i quali "un po 'di conoscenza" è una cosa pericolosa. "Possono o non possono comprendere la documentazione (anche se è probabile che lo siano), ma si sentiranno bene su "essere tenuti al corrente". Questo pubblico include molti tipi "manageriali". Se questo è il tuo pubblico principale, la documentazione del codice automatico potrebbe essere una buona cosa.

la semplice risposta a "perché generare documenti" può essere semplicemente risposta mostrando MSDN.

Immagina di provare a scrivere un programma che usi qualsiasi libreria in cui non ci sia 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 da consumare da altri) allora forse c'è un caso da non disturbare - ma anche allora, quanta parte di una grande, solo-interna, applicazione non contiene mucchio di librerie comunque? Quando ti unisci a un team di questo tipo, avere un documento API navigabile sarà utile.

Nessuno strumento scriverà la tua documentazione per te, ma ti fornirà lo standard che dovrai comunque scrivere manualmente, alcuni strumenti (come doxygen) genereranno anche diagrammi e liste di riferimento (di chiamata e chiamata funzioni per esempio) che non sarebbe facile da scoprire anche 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 caso qualcuno dovrebbe dire "c'è il codice sorgente, questa è una documentazione sufficiente" in qualsiasi momento.