From: Richard Newman (richard_at_[hidden])
Date: 2006-09-18 11:17:09
David Abrahams wrote:
> Richard Newman <richard_at_[hidden]> writes:
>
>> IMHO, proper detailed documentation is simply readable
>> code.
>
> This is part of the reason I have such a hard time with XP.
>
> The first problem is that the author of a piece of code almost
> invariably overestimates its readability. It's common that even the
> original author can't understand what he was doing after 6 months go
> by.
I agree. All the more reason to consider writing it with the layperson
in mind as part of the audience. One will take more care to avoid
obscuring detail. Even when I didn't follow XP, I still thought this
point was a good idea for the reason you just gave.
>
> The second problem is that you can't determine the correctness of code
> by looking at it without a specification. The redundancy provided by
> documentation is important.
I never suggested that one doesn't write specs. At the very least, TDD
might be a minimal substitute for specs if you had nothing else. My
point was more in response to not having to repeat the code in natural
language documentation when we could certainly avoid writing obscure
code in the first place.
>
>> 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.
>
> You're seriously suggesting that the layperson can read the code and
> assess what the product does?
As I said before, only to a degree. I don't see why this has to be
viewed as a dichotomy rather than a continuum. We can write code that
is less obscure, that where at all possible and certainly at higher
levels, can reveal algorithms that can be followed by laypersons. I'm
not suggesting we expect laypersons to know the distinction between
passing parameters by reference or by value, but if the code lays out
its approach in reasonable objects and method construction for the
domain space, laypersons likely can follow the gist of what is being
done and evaluate how well the code reflects intent.
The effort to do so would acknowledge the value of the ideal even if it
can't always be achieved in practice. Write the code to what it must
do, but do so in a way that allows it to be read by the widest audience
possible.
>> For instance, the tertiary operation
>
> ternary [ie. "?:"] operator?
>
Yes, sorry. I sometimes stumble when I pronounce aluminum too. :)
Regards,
Richard Newman