Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

60%
+1 −0
Q&A Best practices for maintaining documented code examples?

Python has a useful module called doctest. It is commonly used to validate tutorial documentation and examples embedded as comments in the code. The doctest module searches for pieces of text t...

posted 12y ago by Steven T. Snyder‭  ·  last activity 4y ago by System‭

Answer
#3: Attribution notice added by user avatar System‭ · 2019-12-08T02:14:05Z (over 4 years ago)
Source: https://writers.stackexchange.com/a/5300
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by user avatar Steven T. Snyder‭ · 2019-12-08T02:14:05Z (over 4 years ago)
[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.

#1: Imported from external source by user avatar System‭ · 2012-03-22T16:39:44Z (about 12 years ago)
Original score: 12