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 _______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
