Hi Thorsten, all,
Thorsten Behrens schrieb:
Hey, and yes, having a feature documented is _also_ nice
IMHO it is not "nice", but an indispensable part of software
engineering. A spec defines the _intention_ of a piece of software.
Without a clear and documented intention I cannot make something
reliable, something that I want millions of people to use and enjoy.
Code defines the actual behavior. Without a I do not know, if that
matches the intention.
You once said, as long as nobody complains, that does not matter. I am
not so sure. E.g. if some code has specific security features and that
is not documented in a spec, further development may destroy that
feature. Nobody will complain, until it is too late (security was hurt).
Or some code aligns to a good UI rule, or some code provides output in a
format that can be understood by another program. Such things are not
always obvious and can be broken easily, if there is no spec.
> Fixing the root cause of your problem is not providing more
documentation, but providing more automated testing.
Tests (unit tests) check, if the code fulfills specific contracts. But
tests can have errors or get outdated. Without a spec, one cannot say,
if the code or the test is wrong.
As for the additional effort - should we require everyone to do this?
My thoughts: Contributing to OOo can be (and of course should be) fun,
especially for those doing this in their free time and out of
enthusiasm. But just, if I do something for fun, I normally want it to
be something useful, don't I? If I contribute to OOo, I expect some
million people to use the product with my additional feature and enjoy
it. Is it really a tall order, if then I not only do the "fun-part"
(coding), but also some things that are less fun, but helpful for a
professional outcome?
Specs often are finished only after writing the code. That is because
our imagination is limited. Often we need a tangible example, before we
know what we really "wanted". There is nothing wrong about changing and
polishing a spec after having written the code.
Still also the spec "after the fact" needs to reflect the _intention_ of
the software. If the spec simply documents that code behaves unusable,
than it can work as documentation for QA etc., but there would be still
a bug: Its a pain for the user.
Also the spec can not (must not) say anything about the design. A spec
says _what_ the program does, not _how_.
Having said all that, nevertheless the overhead should be as small as
possible. There is no sense in writing a spec, just for having one. For
many features the spec may only need two sentences or 10 lines. And then
it needs to be possible to indeed make it as short.
Nikolai
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
