Richard Newman <richard@cdres.com> 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
David Abrahams wrote: 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