La documentazione estesa è un codice olfattivo? [chiuso]

Non avere alcuna documentazione e pensare che IntelliSense sia tutto ciò che serve per comprendere i dettagli più fini e più sottili di ciò che ogni classe / metodo fa, è illusorio.

Ci sono naturalmente dei casi molto semplici - per esempio, se una classe List ha una proprietà Count , cosa potrebbe restituire quella proprietà tranne l'ovvio. Ma una quantità molto significativa di metodi ha proprietà d'angolo o proprietà comportamentali che devono essere documentate a vantaggio dell'utente API.

Facciamo un esempio:

public static TabPage ContainingTabPage(this Control control);

Pensi che sia ovvio come funziona il metodo? Bene, la sua intenzione è sicuramente chiara, ma ... cosa succede se il controllo non è contenuto in nessun TabPage ? Restituisce null o getta? Cosa succede se è in più TabPages nidificati? - Fortunatamente, la documentazione risponde a queste domande: Se questo controllo si trova all'interno di TabPage, restituisce il primo TabPage rilevato iterando ricorsivamente attraverso i suoi genitori. Altrimenti restituisce null. Quale sarebbe il metodo da chiamare per rendere ridondante questa documentazione? %codice%? Ciò non contribuisce alla leggibilità del codice.

O prendi qualcosa di simile a questo:

/// <summary>
/// Returns the smaller of the three IComparable values. If two values are
/// equal, returns the earlier one.
/// </summary>
public static T Min<T>(T val1, T val2, T val3) where T : IComparable<T>;

Nella maggior parte dei casi la seconda frase nella documentazione è irrilevante, ma non fa male. Nei pochi casi in cui è importante, può farti risparmiare un sacco di tempo - se non hai il codice sorgente, dovresti trovare la risposta per esperimento. In questo caso l'esperimento è facile, ma immagina che il metodo riguardi la concorrenza e ti stai chiedendo quali siano le condizioni di sicurezza del filo o della razza ...

Un altro esempio: prendi un serializzatore XML. È semplice, potresti pensare, avere solo un InnermostContainingTabPageOrNull() e un XElement Serialize<T>(T) metodo ed è assolutamente chiaro che cosa fanno! Uhm, beh, eccetto ... come si serializzano i dizionari? Come gestisce le interfacce? Conserva l'identità dell'oggetto? Fa fronte a riferimenti ciclici senza andare in loop infiniti? Come si comporta di fronte alla sfida di serializzare delegati, risorse native, proxy remoti? Quali tipi di eccezioni generano in quali situazioni?

Solo avere due metodi non significa che il processo di serializzazione dei dati sia semplice. Di conseguenza, il nostro serializzatore XML personalizzato ha un grosso blocco di documentazione sulla classe che descrive, in dettaglio, tutte le sue caratteristiche e tutti i suoi limiti; che tipo di classi può serializzare, quali supposizioni fa e quali eccezioni genera; gli attributi personalizzati che è possibile utilizzare per modificare il suo comportamento; e, forse la cosa più importante, quali sono le idee di progettazione fondamentali che stanno dietro e quali casi d'uso intende coprire (in modo che se il tuo caso d'uso è sufficientemente diverso, sai che potresti scegliere un serializzatore diverso).

Ora, con tutto ciò che ho detto, penso che ci sia qualcosa da dire su qualità vs. quantità . Molte librerie create per hobby sono fornite con file HTML aggiuntivi o altri documenti contenenti un mucchio di documentazione di bassa qualità quando potrebbero essere più utili con la documentazione meno ma migliore . Una buona documentazione deve soddisfare due importanti funzioni:

• Che cosa fa questa classe / metodo? - Questo è facile, basta documentare ogni classe / metodo.

• Come faccio a fare X? - Questo è difficile. Potrebbe non essere ovvio all'utente API quale sia il metodo o la classe di cui hanno bisogno. Per coprire questi casi, spesso aiuta se la documentazione di un metodo si collega ad un altro (es. "Se stai cercando di fare X, preferisci usare M") o la documentazione di una classe menziona tutte le altre classi con cui interagisce (ad esempio il nostro serializzatore XML sopra menzionato elenca tutti gli attributi personalizzati che lo influenzano). Alcuni piccoli esempi di codice per scenari comuni possono essere utili, ma solo se non sono banali.

Ci deve essere un piccolo set di posti dove cercare la risposta. Se l'utente dell'API ritiene di dover leggere pagine dopo pagine di materiale irrilevante solo per accertarsi che la risposta che sta cercando non ci sia, la documentazione è troppo strutturata e l'utente dell'API potrebbe anche non preoccuparsi di leggere se è più facile e veloce chiedere su StackOverflow.

Quindi, in sintesi: No, la documentazione estesa non è affatto un codice olfattivo . Certamente non puoi migliorare il codice semplicemente rimuovendo la documentazione. Ma potrebbe essere un odore di documentazione . C'è una buona documentazione e una cattiva documentazione, e in alcuni casi una cattiva documentazione può essere migliorata tagliandola. Aggiungere ulteriore documentazione può peggiorare la documentazione. La qualità della documentazione non è misurata in base al numero di parole, più di quanto la qualità del codice sia misurata da linee di codice.

Per le librerie e le API pubbliche, una buona documentazione con codice di esempio semplifica l'adozione di molto . La documentazione non deve essere estesa (i documenti in stile javadoc su ogni metodo sono spesso inutili), ma dovrebbero fornire un'introduzione al punto su concetti e struttura di base, nonché esempi su un modo corretto per eseguire attività comuni con l'API.

Ci sono decisioni di progettazione, modelli e pratiche raccomandate che un utente non può facilmente racimolare entro un ragionevole lasso di tempo semplicemente guardando il codice, a meno che l'API sia estremamente semplice (il che non è sempre possibile).

Non sono sicuro di quali librerie open source hai visto, perché la maggior parte ha una schifezza per la documentazione. Detto questo ...

Innanzitutto, prima che decida di voler utilizzare una libreria, vorrei vedere alcuni documenti che spiegano se farà esattamente quello che mi serve - preferirei non dover scaricare e cercare attraverso la fonte codice per capirlo.

È anche molto più facile cercare attraverso un file di documentazione la funzionalità desiderata piuttosto che cercare il codice sorgente. Non m'importa quanto chiaramente tu (pensi di aver) chiamato le tue lezioni, qualcuno non si renderà conto che la classe Fuu fa davvero Foo. Una spiegazione scritta in inglese mi aiuterà a risolvere questo problema.

La documentazione API sotto forma di javadoc (ad esempio) può anche essere collegata direttamente al codice sorgente all'interno di IDE (come Eclipse), che può anche rendere molto più semplice il lavoro con la libreria.

Quindi no, la documentazione estesa è una buona cosa. Non devi leggerlo se non vuoi, ma lo faccio.

Insinuando con le altre due risposte (+1 per entrambe), le buone API sono buone da avere, ma una buona documentazione è essenziale. Forse la documentazione non è necessaria per un pacchetto molto semplice, uno in cui ogni oggetto / ogni funzione si regge da solo, e ogni oggetto / ogni funzione fa esattamente quello che ci si aspetterebbe. Un semplice pacchetto di matrice / vettore matematico, ad esempio, potrebbe essere auto esplicativo. Poi di nuovo, forse no. Persino quei semplici pacchetti spesso contengono un'ampia documentazione. Quale decomposizione della matrice è la migliore per questa situazione? Per quello? Le operazioni di matrice non elaborate inevitabilmente distruggono la memoria. Un buon pacchetto mi dirà come utilizzare le parti del pacchetto in combinazione in modo da evitare questi problemi. E questo è un semplice pacchetto.

In un pacchetto giocattolo per un problema giocattolo, gli oggetti e le funzioni non interagiscono, non ci sono dipendenze e le interfacce sono ovviemente ovvie solo dall'API. La vita di solito non è così semplice, e nemmeno la maggior parte dei pacchetti software.