Re: [boost] Interest in a Behavior Driven Development Framework

From: Joel de Guzman (joel_at_[hidden])
Date: 2006-09-15 19:43:33

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