It is popular to write documentation in the same file as the code and extract that using a >software to generate documents.
Sì, è popolare - per librerie software e la loro documentazione. Immagino tu stia parlando di quel tipo di documenti (e non, per esempio, i manuali utente).
And that often results in cumbersome source file.
Beh, questo è abbastanza discutibile. Se fatto con cura, IMHO la documentazione è esattamente al suo posto - in vista della cosa che descrive, quindi quando guardo la firma o l'implementazione del metodo, devo anche descrivere brevemente le intensità di quel metodo a portata di mano.
Doesn't it make more sense to write documentation in the same file as tests not in commented lines but in ordinary language using DSL?
Vedo alcuni problemi qui:
-
nei tuoi documenti, in genere desideri uno schema generale della tua classe e una descrizione per ogni metodo o proprietà pubblica della tua classe. Quindi i documenti seguono nella struttura esattamente la struttura delle classi, ma i test hanno in genere una struttura diversa. Per un metodo specifico, di solito hai più di un test, per una classe avrai molti test e per una proprietà potresti non avere alcun test.
-
quando si posizionano i documenti non direttamente sopra un metodo, si dovrà ripetere la firma del metodo e il nome della funzione completi nella posizione dei documenti, per rendere leggibile la descrizione, quindi questo porta a una qualche forma di ripetizione indesiderata del codice . Posizionare il documento sopra il metodo lo evita.
I documenti -
nelle vicinanze della funzione documentata hanno la più alta possibilità di essere aggiornati con il codice quando qualcosa viene cambiato. Quando metti i tuoi documenti da qualche altra parte, riduci significativamente questa possibilità.
Quindi la mia risposta è - no, non mi piace l'idea (ma mi piace la domanda, quindi +1 per quello).
Ciò che mi piace, tuttavia, è l'idea di utilizzare i test come parte della documentazione (non la documentazione completa, sono la parte degli esempi, ma non descrivono i requisiti generali). La documentazione potrebbe fornire riferimenti a test specifici che mostrano un comportamento di esempio e uno strumento di estrazione di documenti potrebbe utilizzare tali riferimenti per creare un documento formattato in cui sono inclusi quegli esempi (non so se tale strumento esiste, ma forse sarebbe una bella novità funzionalità per uno dei prodotti disponibili).