David Pratt wrote at 2008-3-11 09:42 -0300:
I think your response gets to the heart of the issue. For software to be useful, it is often more important for folks other than the author to understand it. This can only occur with communication. Sometimes it is the understanding of edgecases in particular, that gets lost over time.
The are different understanding levels: e.g. the level of understanding needed by the user of a piece of software and the level of understanding needed by its maintainer. I use e.g. "gcc". To do this, I need a basic understanding of the programming language, the compilation process, the "gcc" options and arguments and how they influence the compilation and build process. I need nothing to know about edge cases in the compiler implementation. I also do not need doctests -- not even those that provide examples for the various options (think e.g. of doctests for the options "-m64", "-Wunused-label", "-O3" -- all of them are better described by words (only) rather than doctests). Would I be a "gcc" maintainer, I would need a very different understanding. Tests would be vital (though not necessarily doctests). However, more important would be a good understanding of compilation concepts and how they have been implemented in the "gcc" implementation. I find another point essential: communication is not limited to tests. I find tests (examples) a bad communication vehicle -- see the "gcc" examples above. A clear concept description and an outline how the concepts are used in the implementation, well chosen names, good source code comments at difficult places are additional communication means -- often better ones as doctests....
... If the test is worth writing, it is not difficult to add a small amount of text to communicate about it. If the software is worth writing in the first place, I consider the code incomplete without doctests. For community projects, it is often the case that it is not the author maintaining the code in the future. This only strengthens the argument for doctests and the reason this has become the standard for zope.
There are other means beside "DocTest"s for communication and documentation -- often better ones.... -- Dieter