Richard Newman wrote:
Joel de Guzman wrote:
But why would a layperson have to read pseudo-english embedded in arcane C++ when she can read the documentation? IMO, (sorry Dean) all this hoopla is just an elaborate excuse not to write proper detailed documentation. IMO, programs that end up overly complex and rife with potential error stems from the lack of documentation and design discipline. Code goes haywire and get into a tangled mess, and hence become unreadable in the process. It does not start from unreadable code, it starts from lack of, inadequate, or improper documentation.
Two reasons come to mind: (1) often writing "proper detailed documentation" isn't appropriate, and (2) translation error.
Writing separate documentation isn't always appropriate or desired. For instance, in an XP scenario, you only write that documentation that will be immediately useful: users' guides and the like; it would be an undesired weight on the development effort to write internal code construction documentation. You count on the code construction and the unit tests to directly communicate the notions to follow on programmers.
Even with XP, there's planning and design. I sure hope that would be documented before and after coding (when there are changes from the specs). The plan and design is more important to the layperson. Without it, it's simply hacking in the guise of XP. I wouldn't trust anyone to build my house without design and a plan detailed in documentation.
Further, writing documentation of the algorithms at a detailed enough level to understand what the details of the design was may have a cost at least as high as writing the code itself. At the very least, the code itself should communicate to the next reader, be it layperson or programmer, what the design was; otherwise, we could go back to 4 letter variable names. Since you go that far, why not have the discipline to write readable code, readable at least at some level by the layperson?
Oh my. Do you expect the layperson to read your code? Consider a code snippet (the humble for_each) lifted from STL (from g++): /** * @brief Apply a function to every element of a sequence. * @param first An input iterator. * @param last An input iterator. * @param f A unary function object. * @return @p f. * * Applies the function object @p f to each element in the range * @p [first,last). @p f must not modify the order of the sequence. * If @p f has a return value it is ignored. */ template<typename _InputIterator, typename _Function> _Function for_each(_InputIterator __first, _InputIterator __last, _Function __f) { // concept requirements __glibcxx_function_requires(_InputIteratorConcept<_InputIterator>) __glibcxx_requires_valid_range(__first, __last); for ( ; __first != __last; ++__first) __f(*__first); return __f; } I would be thankful for the documentation written prior at the top. There's no such thing as self documenting code. I don't think BDD will even help in documenting the intent of the algorithm. Give it a shot and see if you can capture the intent: "Applies the function object f to each element in the range[first,last). f must not modify the order of the sequence. If f has a return value it is ignored.".
Why write it twice: once in code and once in natural language? Perhaps I've not correctly interpreted what you mean by "proper detailed documentation." IMHO, proper detailed documentation is simply readable code.
Or maybe I've not correctly interpreted what you mean by "documentation is simply readable code". 1) Is the code above equally readable without the documentation at the top? 2) How would you capture the behavior of the algorithm with BDD?
Second, every time you translate between the spec and the code, you introduce the possibility of translation error. It's bad enough when under classic lifecycles, you might translate from spec to analysis models to design documents to code to test scripts, then you add documentation to describe what you did. It may not be reasonably as Rene pointed out to do this directly from spec to code, but from reconciling from code to spec ought to be possible. At some degree, having the code clearly reflect the algorithms involved, such that a layperson can assess what product does, allows these translation layers to be reduced.
The question is how BDD can help write code that clearly reflects the algorithms involved. Try the simple for_each, see if you can convince me. Then try a more elaborate algorithm, say, quicksort. See if you can capture the essence of the algorithm in BDD. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net