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
>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....
Zope-Dev maillist - Zope-Dev@zope.org
** No cross posts or HTML encoding! **
(Related lists -