Communition over implementations (was: [Zope-dev] Re: zope.sendmail Retry fixes and new state machine.)

[Dieter Maurer]

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