Skip navigation.

Papers - Accu CVu 21(6)

Reflection on Code Critique 60

Martin Moene < m.j.moene@eld.physics.LeidenUniv.nl>

Proto-pattern: Machine-tested Program Text[1]

Context   As an author you are drawing attention to certain properties of software. You illustrate this with example code.

Problem   Books and articles are proofread and corrected to prevent errors in them as much as possible, however this does not guarantee error-free texts. Errors in code examples must not occur as they may confuse a reader who is not yet sufficiently familiar with the subject at hand. Unlike non-code text, the software examples can be executed and tested for correct behaviour mechanically.

Forces  t.b.d.

 Solution   Test the example code with a unit test and present the tested code in the article or book.

Positive Consequence   Provided with error-free examples, your readers may have an easier time to understand the point you are making.

Negative Consequence   Some people may become less alert reading a text when they cannot spot an occasional error.

Known Uses   In The Practice of Programming, Kernighan and Pike write: "...  We've tried hard to write our own code well and have tested it on a dozen of systems directly from the machine-readable text."[2a]

In The C Programming Language, Kernighan and Ritchie write: "As before, all examples have been tested directly from the text, which is in machine readable form."[2b] 

In The AWK Programming Language, Aho, Kernighan, and Weinberger write: The examples have all been tested directly from the text, which is in machine readable form."[2c]

Well, a clear pattern emerges here.

Related to this are texts created with a literate programming system (http://en.wikipedia.org/wiki/Literate_programming), such as [2d] and [2e].

Discussion  I'm not sure if we may call this a proto-pattern or that it's merely a good practice forced into pattern form[3]. Although presented as a stand-alone pattern, it could also be part of a pattern language for authoring software articles. Maybe one even already exists, even though I did not find one.

Notes and References
[1] Inspired by #include <iostream> missing from test.cpp; as the author mentions shortcomings of the program's output ("the second output is wrong"), it must have been created from a different version than from the source code shown (or it must be that <string> or <vector> of the compiler used by the author has the side-effect of making std::cout available; MS VC8 does not do that).
[2a] Brian W. Kernighan and Rob Pike. (1999). The Practice of Programming. Addison–Wesley. p. xi.
[2b] Brian W. Kernighan and Dennis M. Ritchie. (1988). The C Programming Language. Prentice Hall, second edition. p. ix.
[2c] Alfred V. Aho, Brian W. Kernighan, and Peter J. Weinberger. (1988). The AWK Programming Language. Addison–Wesley. p. v.
[2d] Christopher W. Fraser and David R. Hanson. (1995). A Retargetable C Compiler, Design and Implementation. The Benjamin/Cummings Publishing Company, Inc.
[2e] Allen I. Holub. (1990). Compiler Design in C. Prentice Hall, second edition.
[3] Frank Buschmann, Kevlin Henney, and Douglas C. Schmidt. (2007). Pattern Oriented Software Architecture: On Patterns and Pattern Languages, Volume 5. John Wiley & Sons.