Hi Mathias,
On 10/31/06, Mathias Bauer <[EMAIL PROTECTED]> wrote:
Kohei Yoshida wrote:
> 2) The target audience is not very clear. Thanks to this thread,
> though, now I'm beginning to see who the specification documents are
> intended for (mostly for QA, right?).
Not exclusively. Also developers will benefit from a spec if they have
to refactor/change/extend the code later on. Believe me, I can't count
the occasions any more where I would have been glad to have a
specification for a feature that needed a larger rework. Without a spec
we very often are standing in the dark and hope to be lucky not to
damage too much things just because we just don't know about their
existence. If you contribute features to a project you should see that
you add something useful to the project but also a legacy for the code
owner who has to maintain your code in the future. Code alone isn't
documentation enough, even for developers.
I fully agree that, there are clearly cases where a correctly written
specification can save your day, as you pointed out above. But there
are also cases where, because of an incorrectly written
specification/documentation/inline comments, you could end up wasting
time in the end.
I'll give you an example. One day I was working on adding a new
feature to an existing application (this is not OO.o BTW). So, I
started tracing the existing code, which was pretty well documented
with lots of header comments, to try to figure out where best to add a
hook for that new functionality. I found the right point of insertion
and added the hook, but somehow the code didn't work as expected. So,
naturally I started tracing the whole call stack to figure out what I
was doing wrong. I literally traced all the way down to the main()
function. Still no luck finding the root cause of the problem. Since
each method had a pretty good header comment, I read those comments
fully and trusted that they were all correct (the original code author
was long gone and unavailable).
It turned out that, the root cause of the problem was not because of
what I was doing wrong, but because one of those function's comments
specified the wrong return value (e.g. "return 0 on success, and <0 on
failure" type of comment). Once I realized that, and made necessary
changes in my code as well as in that incorrect header comment, things
started to work. It took me a whole day to realize this.
So, while I agree that, when you *know* with certainty that the
documentation/specification is correct, it will help save your day.
But you cannot always make that assumption. Sometimes, the
documentation may be incorrect, but the code still speaks for itself.
Anyway, I'm not trying to agree or disagree. I just wanted to offer a
counter example. :-)
Kohei
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
