Boost logo

Boost :

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.


Boost list run by bdawes at, gregod at, cpdaniel at, john at