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

From: Richard Newman (richard_at_[hidden])
Date: 2006-09-18 10:56:22

Sorry, I'm behind; I didn't follow the thread over the weekend.

Joel de Guzman wrote:
> 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.
Agreed.  My earlier comments were more addressed to the notion of 
documenting only for the sake of documenting.  Most useful design 
processes result in useful documentation as a result of the design 
approach and are not written after the fact to fulfill some kind of 
procedures standard.  The best approaches produces documentation almost 
as a necessary side effect.

I generally ask individuals to write out their proposals and present 
them to one another and others to a level of detail necessary to convey 
to the involved stakeholders that each understands the other.  Is it 
exhaustive in detail?  No, not at all.  Does it provide a framework and 
criteria for measuring successful results?  Yes.  They iterate and 
refactor on that just as they would the code.

Such writing is their tool and platform for working out their approach 
and reaching agreement.  As a result we end up documentation without 
having to do it after the fact or add more weight to the process.  It 
may not be in a standard format or prove how every detail will work with 
certainty, but it does provide the essential 80% of what we do need to 
reasonably approach the problem.

> 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.".
But you did do what I asked for!  I never said that you can't have 
comments, though one's reliance on them should be as minimal as 
possible.  In this example, you have variable names that convey their 
role (except "_f" might have been better as "_function") and I probably 
would have used braces and indentation for the inner single line 
for-loop.  Style points to be sure, but ones that might allow a 
layperson to more easily grasp the code's intent.

I think my point is one that we probably take as a best practice anyway: 
you do in the code what must be done so that next reader can understand 
what you were trying to do and why you did it.  We often have to contend 
with other programmers, let alone laypersons, who would struggle to read 
the above code without documentation.  Why not accept that and have the 
discipline to make it readable to a somewhat broader audience. Even so, 
I could reasonably get across the gist that this loops through 
everything passed to it and applies a given function.  I'm not 
suggesting that we dumb code down and avoid language constructs, just 
that we don't make its meaning more obscure than necessary.

I'm not suggesting that a layperson will follow the detailed nuance of 
it.  But client code using the above code will now likely use a more 
readable for_each loop and the semantics are somewhat more clear to 
non-C++ readers.

As I said in my earlier post, I'm not expecting 100% solvency here, just 
that we consider the code, with its test cases, a key part of the final 
documentation.  Any documentation that attempts to restate the code 
after the fact will likely introduce translation errors and increase 
maintenance.  Indeed, even the comments can suffer this, but at least 
they're inline where they can be considered at the same time.

If we take care to have the code, especially at higher levels, clearly 
depict the logic for a wider audience, we can better assure that we're 
consistent with specs.  Unfortunately, programmers are often too clever, 
  writing something that never matches the problem statement in its 
construction and that has dubious performance improvements.  Yes, it 
might be for that day, for that set of tests, they might have had 
results that matches results expected in the specification, but if it 
doesn't follow the same approach, how can we reasonably validate its 
side effects and bounds of performance?  Instead you have a scenario 
where the sponsor asks did you do item A and the programmer nods yes and 
points at a couple of tests but really they did B or some variant of A 
that if the sponsor could read it would realize some essential point of 
departure that hadn't been thought of to measure in the tests.

> 
> 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?
As I said in my first post, I'm struggling my articulation of this 
notion and avoiding some realm of Colbert-ian truthiness given that I 
don't have any bright lines.  But it seems to be a Good Thing if code 
can reflect the problem statement as close as possible and to be written 
in a way that reduces how arcane it is so that stakeholders can 
participate in its direct review.

> 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.
I wasn't acting as a proponent or opponent of BDD as I'm not familiar 
with it, but would too invite those BDD proponents to respond.

My first post was in response to Rene Rivera's comment with regard to 
the dark days of laypersons coding.  I agree with that sentiment 
(something about Shakespeare and monkeys comes to mind), but think that 
there is a middle road that would improve our practice.  If I've 
distracted the thread, I apologize, but it seemed a good opportunity to 
let others beat on this straw-man I'm wrestling with.  I very much 
appreciate your responding to my posts.

Regards,
Richard