Post History

Source: https://writers.stackexchange.com/a/5300
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

[Python](http://www.python.org) has a useful module called [`doctest`](http://docs.python.org/library/doctest.html). It is commonly used to validate tutorial documentation and examples embedded as comments in the code.

> The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use doctest:
> 
> [...]
> 
> To write tutorial documentation for a package, liberally illustrated with input-output examples. Depending on whether the examples or the expository text are emphasized, this has the flavor of “literate testing” or “executable documentation”.

Since the code you're interested in is merely _excerpts_ from the full source, you would extract the excerpts from the tested code based on some metadata. Tools like [Doxygen](http://doxygen.org/) are intended for this purpose.

A language-agnostic approach would be to include the full source for each excerpt in the library source code or wherever the primary documentation resides. Then when you want to build your tutorial/developer guide, you run automated tests on the code using your xUnit-equivlent with `doctest`-like connector code if necessary, and then extract the excerpts with [Doxygen](http://doxygen.org/).

Regardless of what specific solution you implement, best practice for maintenance is to follow the [DRY principle](http://en.wikipedia.org/wiki/Don%27t_repeat_yourself). Do what you can to keep all of the source code in one place. In your case, it sounds like this will require generating your excerpts from the original sample code each time you generate the documentation. There's some discussion on the topic of code sample testing and maintenance in [The Pragmatic Programmer](http://pragprog.com/the-pragmatic-programmer) on pages 26-29 (DRY principle) and further on pages 100-[101](http://books.google.com/books?id=5wBQEp6ruIAC&lpg=PA101&ots=n4irfyaOt_&dq=%22we%20didn%27t%20want%20to%20copy%20and%20paste%20lines%20of%20code%20from%20the%20tested%20programs%22&pg=PA101#v=onepage&q=%22we%20didn%27t%20want%20to%20copy%20and%20paste%20lines%20of%20code%20from%20the%20tested%20programs%22&f=false). The authors describe vaguely how they accomplished what you need:

> [...] using the DRY principle we didn't want to copy and paste lines of code from the tested programs in the book. That would have meant that the code was duplicated, virtually guaranteeing that we'd forget to update an example when the corresponding program was changed. For some examples, we also didn't want to bore you with the framework needed to make our example compile and run. We turned to Perl. A relatively simple script is invoked when we format the book -- it extracts a named segment from a source file, does syntax highlighting, and converts the result into the typesetting language we use.

Original score: 12