Gli esempi di utilizzo nella documentazione XML dovrebbero essere testati esplicitamente?

Question

Gli esempi di utilizzo nella documentazione XML dovrebbero essere testati esplicitamente?

#1 da (2 voti)

0

Se gli esempi di utilizzo sono forniti nella documentazione XML, questi esempi dovrebbero essere esplicitamente testati?

/// <summary>
/// Gets a collection of Foo objects. 
/// </summary>
/// <param name="bar">The model database connection.</param>
/// <example>Example code for using this method.
/// <codelang = "vb">
/// Dim bar As New Bar()
/// Dim foos As ReadOnlyCollection Of Foo) = helperClass.GetFooFromBar(bar)
/// </code>
/// </example>
public ReadOnlyCollection<Foo> GetFooFromBar(Bar bar)

Certo, il precedente esempio inventato non è probabilmente a rischio di regressione, ma sarebbe molto imbarazzante se gli utenti API incollassero il codice di esempio e non funzionasse.

Supponendo che l'opinione di consenso è che questi esempi di codice dovrebbero essere testati, la domanda successiva è Come è possibile automatizzare questi tipi di test per eliminare il più possibile l'errore dello sviluppatore

testing c# documentation xml code-sample

posta Michael J. 25.07.2017 - 19:30

fonte

1 risposta

Leggi altre domande sui tag testing c# documentation xml code-sample

Un repository dovrebbe trasformare i dati nel modello corretto? Gateway API: filtraggio dei dati tra microservizi

score 2 · Answer 1

Personalmente, sì, credo, dovrebbero essere testati. Un sacco di gente dice che una delle cose brutte dei commenti alla documentazione è che non vengono controllati dal compilatore. Bene, qui hai almeno una parte del tuo commento sulla documentazione che può essere controllato da un framework di test, quindi fallo!

Ci sono alcune direzioni interessanti in cui questa idea può essere sviluppata: la comunità Python ha una libreria chiamata doctest , che può estrarre automaticamente esempi di utilizzo (che a loro volta sono (o assomigliano) copia e incolla le sessioni REPL incollate) dalla documentazione e trasformali in unit test.

E un esempio più estremo è il libro Sviluppo web agile con Ruby on Rails , che è un intero libro (non solo un piccolo commento di documentazione), in cui ogni esempio di codice è completamente eseguibile. Ed è eseguibile in due modalità: puoi eseguire il libro su una versione di Rails e il framework assicurerà che tutti gli output siano gli stessi di quelli stampati nel libro; in questa modalità, il libro funge da suite di regressione (e specifiche informali) per Rails. E nell'altra modalità, puoi far sì che il framework aggiorni automaticamente i risultati stampati nel libro per abbinarli a quelli di Rails. Pertanto, è possibile utilizzare gli esempi di codice per garantire che Rails non cambi in modi incompatibili all'indietro, oppure è possibile utilizzarlo per garantire che gli esempi nel libro siano aggiornati con le modifiche incompatibili all'indietro in Rails. IOW: il framework può automaticamente catturare tutte le differenze per te e puoi decidere consapevolmente per ciascuna di esse se cambiare Rails per abbinare il libro (nel qual caso hai già un caso di test non valido da correggere) o cambiare il libro per abbinare Rails (e il framework può fare il secondo per te).

Quindi, se si eseguono gli esempi di codice nella documentazione, si individueranno casi in cui la documentazione non corrisponde più al codice e si può decidere se si è trattato di una modifica intenzionale (e aggiornare la documentazione di conseguenza, anche automaticamente dato il giusto strumenti), un bug nella documentazione o un bug nel codice (nel qual caso l'esempio agisce già come un test fallito).