La migliore pratica per scrivere esempi

Question

La migliore pratica per scrivere esempi

#1 da (2 voti)
#2 da (2 voti)
#3 da (0 voti)

1

Ho scritto alcuni progetti. Provo ad annotare o commentare tutti i possibili (difficile dire se correttamente per spiegare in modo pulito).

Vorrei scrivere la documentazione per questo, ma ho problemi con gli esempi.

Non è un problema scrivere in annotazione sopra ogni funzione (dove è veramente necessario) esempi di tutti i possibili usi di quella funzione - ma sarebbe bello descrivere ciascuno di questi esempi.

E per questo, sarebbe meglio usare un file aggiuntivo dove verrà scritto nel miglior modo possibile. Ma quale formato e quale tipo di file utilizzare per questo?

La domanda secondaria è (in parte correlata a quella principale), che non sono sicuro se sia necessario fare degli esempi in esecuzione . Perché in caso di funzioni memorizzate in caratteri è probabilmente molto difficile fare quegli esempi in esecuzione .

documentation

posta Václav 02.02.2016 - 16:32

fonte

3 risposte

Leggi altre domande sui tag documentation

Algoritmo per ottenere tutti i percorsi in un albero Qual è il nome corretto per questo oggetto dati?

score 2 · Answer 1

In generale, utilizza il formato Markdown.

La maggior parte dei generatori di documenti può leggere i file markdown da includere nell'output della documentazione. doxygen , ad esempio, può includere testo di markdown in linea o da file esterni.

Se gli esempi dovrebbero essere completi o meno dipende da te. Alcuni esempi complessi mostrano solo il codice necessario in modo che le parti estranee non interferiscano con l'esempio. Personalmente, farei una distinzione tra esempi di codice di utilizzo e demo del programma. i programmi compilabili e eseguibili dovrebbero essere inclusi separatamente in modo che l'utente possa vederli funzionare. Questi non fanno realmente parte della documentazione a meno che non prendiate sezioni e incollatele come esempi.

score 2 · Answer 2

Gli esempi di codice dovrebbero illustrare l'uso.

Ad esempio, ecco un commento che ho scritto per un motore di regole aziendali in C #:

/// <summary>
/// Creates LINQ expressions that represent validation rules, and compound
/// expressions representing rule sets via the use of the And and Or methods below.
/// </summary>
/// <remarks>
/// This class is a re-implementation of Joseph Albahari's Predicate Builder class
/// with two type parameters instead of one and some additional utility methods
/// and logging. See http://www.albahari.com/nutshell/predicatebuilder.aspx
/// </remarks>
/// <example>
/// Suggested usage:
/// <code>
/// <![CDATA[
///      var licenseNumberMustMatch = Rule.Create<CacheRecord, AnswerLicense>((ed, al) => string.Equals(ed.RegistrationNumber, al.LicenseNumber, StringComparison.InvariantCultureIgnoreCase));
///      var legalEntityNameMustMatch = Rule.Create<CacheRecord, LegalEntity>((ed, le) => ed.LicenceeName.EntityMatches(le.LegalEntityname));
///      var ruleSet = LicenseNumberMustMatch.And(LegalEntityNameMustMatch); // Type inference works here; no need to specify type parameters.
/// 
///      Rule.Execute(ruleset, cacheRecord, answerLicense, logger, "US_DOC Verify");
/// ]]>
/// </code>
/// </example>

Fornendo un esempio completo, lo sviluppatore del software non deve più indovinare quale sia l'implementazione ideale. Infatti, (s) può copiare / incollare l'esempio, cambiare i nomi e i parametri, aggiungere alcune condizioni aggiuntive ed essere pronto per andare.

score 0 · Answer 3

Preferirei sicuramente un codice di esempio eseguibile su una documentazione. La ragione è semplice. Man mano che la tua base di codice si evolve, potresti facilmente "dimenticarti" di aggiornare la tua documentazione. Ciò potrebbe non avvenire con il codice eseguibile poiché gli strumenti di refactoring nell'IDE possono aggiornare automaticamente il codice di esempio. E potresti anche aggiungere test per i tuoi codici di esempio che vengono eseguiti nel tuo sistema CI.