Documentazione del codice: quanto costa troppo?

Question

Quanta documentazione relativa al codice nell'origine .NET è eccessiva?

Alcuni retroscena: ho ereditato una base di codice di cui ho parlato in alcune delle altre domande che ho pubblicato qui su SO. Una delle caratteristiche "quotate" di questa base di codice è una God Class, una singola classe statica con > 3000 righe di codice che comprende diverse dozzine di metodi statici. È tutto da Utilities.CalculateFYBasedOnMonth () a Utilities.GetSharePointUserInfo () a Utilities.IsUserIE6 () . È tutto un buon codice che non ha bisogno di essere riscritto , semplicemente rifattato in un set appropriato di librerie. L'ho pianificato.

Poiché questi metodi si stanno spostando in un nuovo livello aziendale e il mio ruolo in questo progetto è preparare il sistema per la manutenzione da parte di altri sviluppatori, sto pensando a una solida documentazione sul codice. Sebbene tutti questi metodi abbiano buoni commenti incorporati, non tutti hanno un buon (o qualsiasi) doco di codice sotto forma di commenti XML. Utilizzando una combinazione di GhostDoc e Sandcastle (o Document X), posso creare della documentazione HTML piuttosto carina e pubblicarla su SharePoint, il che consentirebbe agli sviluppatori di capire di più su ciò che fa il codice senza navigare attraverso il codice stesso.

Man mano che aumenta la quantità di documentazione nel codice, più diventa difficile navigare nel codice. Sto cominciando a chiedermi se i commenti XML renderanno il codice più difficile da mantenere rispetto a, diciamo, un // comment più semplice su ogni metodo.

Questi esempi sono dall'esempio del documento X :

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
        ///     </code>
        /// </example>
        /// <seealso cref="Remove">Remove Method</seealso>
        /// <param name="Title">The customers title.</param>
        /// <param name="FirstName">The customers first name.</param>
        /// <param name="MiddleInitial">The customers middle initial.</param>
        /// <param name="LastName">The customers last name.</param>
        public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
        {
            // create new customer instance
            Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);

            // add to internal collection
            mItems.Add(newCust);

            // return ref to new customer instance
            return newCust;
        }

E

    /// <summary>
    /// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
    /// </summary>
    /// <value>
    /// An Int value that specifies the number of Customer instances within the
    /// collection.
    /// </value>
    public int Count
    {
        get 
        {
            return mItems.Count;
        }
    }

Quindi mi stavo chiedendo da te: documenti tutto del tuo codice con commenti XML con l'obiettivo di usare qualcosa come NDoc (RIP) o Sandcastle? In caso contrario, come si decide cosa ottiene la documentazione e cosa no? Qualcosa come un'API avrebbe ovviamente doco, ma per quanto riguarda una base di codice che passerai a un altro team per mantenere?

Cosa pensi che dovrei fare?

Answer 1

Penso che una buona parte del problema qui sia la sintassi dettagliata e crufty della documentazione XML che MS ci ha opposto (anche JavaDoc non era molto meglio). La questione di come formattarla è, in larga misura, indipendente da quanto è appropriato.

L'uso del formato XML per i commenti è facoltativo. È possibile utilizzare DOxygen o altri strumenti che riconoscono diversi formati. Oppure scrivi il tuo estrattore di documenti: non è così difficile come potresti pensare di fare un lavoro ragionevole ed è una buona esperienza di apprendimento.

La domanda su quanto sia più difficile. Penso che l'idea di auto-documentare il codice vada bene, se stai scavando per mantenere del codice. Se sei solo un client, non dovresti aver bisogno di leggere il codice per capire come funziona una determinata funzione. Molte informazioni sono implicite nei tipi di dati e nei nomi, ovviamente, ma ce ne sono molte che non lo sono. Ad esempio, passare un riferimento a un oggetto ti dice cosa è previsto, ma non come verrà gestito un riferimento null. O nel codice dell'OP, come vengono gestiti gli spazi bianchi all'inizio o alla fine degli argomenti. Credo che ci sia di gran lunga più informazioni di questo tipo di informazioni che dovrebbero essere documentate di quanto non sia generalmente riconosciuto.

Per me richiede la documentazione in linguaggio naturale per descrivere lo scopo della funzione, nonché eventuali condizioni pre e post per la funzione, i suoi argomenti e i valori di ritorno che non possono essere espressi attraverso la sintassi del linguaggio di programmazione .

Answer 2

Nessuno ha menzionato il tuo codice non ha bisogno di essere gonfiato, la documentazione XML può essere in un altro file:

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

E quindi il tuo metodo Aggiungi non può contenere XML / commenti extra sopra di esso, o se preferisci solo il riepilogo (poiché è unito al file separato).

È molto più potente del formato di immondizia che è Javadoc e derivati ??che trovi in ??PHP / Javascript (sebbene Javadoc abbia spianato la strada alla sintassi XML). Inoltre, gli strumenti disponibili sono di gran lunga superiori e l'aspetto predefinito dei documenti della guida è più leggibile e più facile da personalizzare (posso dire che dall'aver scritto doclet e confrontando tale processo con Sandcastle / DocProject / NDoc).

Answer 3

Qui stai colpendo una divisione critica tra quelli che manterranno le nuove librerie e quelli che consumeranno le nuove biblioteche.

Se sto scrivendo una nuova applicazione e userò queste librerie standard, dovrei ottenere un binario stabile delle librerie e semplicemente importarle nella mia applicazione, non copiare il codice sorgente da una posizione e potenzialmente causare problemi se il codice viene modificato. In tal caso, non avrò accesso a nessuno dei "self documenting" funzioni diverse dal nome del metodo e dai parametri di input / output, e anche quelli non verranno esposti se sto usando un tipo di IDE che non ha la funzionalità di completamento automatico attivata.

Quindi nel tuo esempio di codice sopra, penso che vada bene. Le cose non sono troppo dettagliate all'interno del codice stesso e i nomi sono auto-documentati. D'altro canto, tutti i dati di riepilogo / parametri necessari sono lì in modo che un solido pezzo di documentazione possa essere costruito per consentire a coloro che consumano la libreria di avere tutte le informazioni critiche a portata di mano. Purtroppo XML è piuttosto gonfio, ma in generale penso che la maggior parte degli sviluppatori possa facilmente sfogliare tutto il contenuto di riepilogo e guardare il codice effettivo all'interno del metodo.

Answer 4

Jeff ha un ottimo articolo sul commento (o dovrei dire, non sul commento) qui ...

http://www.codinghorror.com/blog/archives/001150.html

So che non sto rispondendo alla domanda, ma penso che sia un punto valido che il codice dovrebbe essere il più autocompattante possibile.

Answer 5

Tendo a documentare tutti i metodi pubblici nel mio codice; l'utilizzo di GhostDoc lo rende banale. E al fine di ridurre il disordine quando modifico il mio codice sorgente, generalmente comprimo semplicemente i commenti andando prima in "modalità di contorno" (ad esempio usa il comando Contorno di Visual Studio > Comprimi al comando definizioni).

Non ho mai provato Sandcastle, ma apprezzo molto il comfort offerto da Intellisense per i metodi che ho commentato in XML.

Answer 6

Opto sempre per i commenti in formato XML / Javadoc, perché adoro poter sfogliare la documentazione API in un formato sensibile (di solito HTML).

Diventa un problema per sfogliare il codice sorgente effettivo, ma trovo che questo sia generalmente un problema minore, dal momento che Visual Studio è generalmente abbastanza intelligente nel comprimere i commenti XML se necessario.

Answer 7

Non ripeterti.

• Il primo esempio dovrebbe avere un nome di metodo migliore e nessun commento.
• Il secondo esempio non dovrebbe contenere commenti.

Il nome del primo metodo dovrebbe riflettere che è assegnato un nuovo oggetto.

Se tale comportamento è standard in tutto il framework per ogni aggiunta, dovrebbe essere documentato a un livello superiore, non in questo documento API del metodo. Altrimenti, cambia il nome.

I commenti dovrebbero aggiungere informazioni, non nasconderle nel rumore. E ci dovrebbero essere commenti, ove necessario in XML. E dove aggiungono valore.

Non voglio vedere: " restituisce il conteggio " per un metodo chiamato count.

Answer 8

Tutte le funzioni pubbliche devono essere chiaramente comprensibili da qualcuno che abbia familiarità con la tua base di codice, ma NON nella tua sezione specifica senza dover approfondire il codice.

Se hai bisogno di scrivere una breve riga per spiegare cosa fa una funzione, è probabile che tu abbia nominato male la tua funzione / classi. Il nome dovrebbe essere autoesplicativo in quel caso

Se per spiegare è necessaria più di una breve frase, probabilmente è un buon commento

Se ci vuole un paragrafo, probabilmente la tua funzione sta facendo troppo oltre a nomi probabilmente poco chiari.

Di solito è meglio sbagliare sul lato dei commenti SE SEI SICURO CHE SIANO PRECISO . I commenti imprecisi e / o non mantenibili sono peggiori di nessun commento

Quindi applicando queste regole:

Nel tuo primo esempio: " // crea una nuova istanza cliente " è ridondante. Il codice è cristallino. Gli altri commenti sono perfetti. Chiariscono su cosa sta funzionando il codice / quali sono i suoi risultati

Nel tuo secondo esempio i commenti sono uno sforzo sprecato e rendono difficile la lettura. Tutto quello che devi fare è assegnare alla funzione un nome proprio. Non che vago "conto". Questa è una cattiva denominazione.

Answer 9

Di recente ho condotto uno studio che mostra che se hai importanti "direttive", ad es., Caller deve fare X " all'interno di molte specifiche (ad es. "questo metodo fa X, il che significa Y e Z"), c'è un rischio molto elevato che i tuoi lettori manchino le direttive. In effetti, quando vedono una lunga documentazione, saltano la lettura del tutto.

Quindi almeno, separa le cose importanti o usa i tag (chiedimi se usi Java).

Answer 10

Tutto dipende dagli standard utilizzati dalla tua azienda, ma per il mio team documentiamo in cima a ogni funzione come nel tuo secondo esempio (cosa che puoi fare in Visual Studio 2008 premendo " / " tasto 3 volte di seguito nella parte superiore di qualsiasi sottotitolo o funzione !!).

Il primo esempio è eccessivo, in particolare la coppia inferiore di righe in cui ogni riga è commentata. Tuttavia, penso che le cose nell'intestazione della funzione possano essere utili, perché le usiamo molto qui. E sembra essere in qualche modo standard da quello che posso dire da molti altri programmatori.

Answer 11

Ho visto standard di codifica che raccomandano di non commentare il codice di auto-commento e il sovraccarico del metodo. Mentre YMMV, sembra un buon modo per allontanarsi dal "Field _numberOfCars è un numero intero che rappresenta il numero di commenti di tipo" auto che portano a overkill.

Answer 12

I commenti in un'intestazione per la generazione di documentazione sono una buona cosa. Anche inserire commenti in codice per spiegare perché stai facendo quello che stai facendo è di solito una buona cosa. Inserire commenti ridondanti parafrasando ciò che hai fatto non è una buona cosa

Answer 13

Quello che hai mostrato è FAR TOO MUCH. Fai un favore a te stesso ed eliminalo!

Il codice dovrebbe innanzitutto essere auto-documentato, attraverso metodi e nomi di parametri significativi. Nell'esempio che hai mostrato;

Aggiungi cliente pubblico (titolo titolo, stringa FirstName, stringa MiddleInitial, stringa LastName) è perfettamente comprensibile all'intento di ciò che sta accadendo, così come "Count".

Commentare come questo, come hai sottolineato, è puramente rumore attorno a ciò che è altrimenti facile da leggere codice. La maggior parte degli sviluppatori si aprirà presto per esaminare e utilizzare il codice, che si accumulerà attraverso oscura documentazione API generata automaticamente. Ogni volta!

Answer 14

A proposito, secondo " Clean code " (Un ottimo libro, a proposito), si dovrebbe evitare di usare markup HTML / XML all'interno di commenti incorporati nel codice sorgente. Anche se il tuo IDE può creare una buona documentazione quando passi il mouse, è considerato troppo distratto e illeggibile quando navighi solo sulle tue fonti.