Date: prev next · Thread: first prev next last
2010 Archives by date, by thread · List index


Lubos Lunak wrote:
 See? So nobody actually knows what the code really does, and everytime 
somebody changes something there, they possibly have a slightly different 
understanding of the purpose, resulting in even bigger mess. That's yet 
another advantage of documentation - even you yourself are reminded of what 
the code is supposed to do, and everybody touching such code is less likely 
to run into a different direction.

Hi Lubos,

ok, so let me elaborate my (maybe extreme) point a bit.

Documentation is a crutch, a feeble attempt to help us mere humans
to grok big code bases. Good code needs only few comments, because
it speaks for itself - it may need some mission statements on
module- or class level, mostly to get the big picture across. And
that is beneficial on many levels, none the least because, otherwise
the more documentation you have, the higher the likelihood it's
out-of-sync with your code.

Sadly, we don't have good code in most places. So what benefit does
documentation yield? Module- and class-level documentation will
still be a helpful bridge between broader concepts (like "what's an
EditEngine good for", what's the purpose of a "SwFrmFmt"), and
bite-sized pieces of code someone could reasonable look into in
finite time.

But from method-level documentation, I expect a detailed, succinct
description on what the method does, including error conditions,
invariants, pre- and postconditions. Over the top you say? Nope.
Because you'll need to know anyway, to be able to correctly use the
method. 

That's why I'm cautiously avoiding to write detailed documentation
for a function like QuickFormatDoc(bool) - I'll surely miss
something, and even if not, it'll be wrong the day someone adds
another bugfix to the edit engine. You're absolutely right with your
statements above, that method purpose is often fuzzy, even messy -
but that's *already the case* - adding documentation does not make 
it go away!

The thing is, after 15 years of maintenance, most code, especially
high-level one, is the opposite of general-purpose - it's been
tweaked to interoperate with exactly the classes & methods it's
interoperating with today. You need to use it in new contexts? Be
prepared to fix it then. Does documentation help you there? Yes, if
it helps you to understand the broader context quicker. Does
detailed method-level documentation help you? I don't think so, for
application-level code. It has an obscenely bad cost-benefit-ratio -
better go read or debug the code. But you'll want good unit tests,
to make sure your modifications didn't break existing clients (a way
of "documenting" code btw, that's never out-of-sync, and cheaply
verifiable - err, well, ideally ;))

In conclusion, maybe we're somewhat apart conceptually, but when
actually adding documentation, I guess there will be little
differences. I'd especially like to have vcl/tools/svtools classes
reasonably documented - it's a sweet spot between effort, and
benefitting many people at the same time. And you may notice that,
if you find doxygen-style documentation in some gui, gfx, or impress
header files, it's from me. ;)

Cheers,

-- Thorsten

Attachment: pgprtQoMF43to.pgp
Description: PGP signature


Context


Privacy Policy | Impressum (Legal Info) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Creative Commons Attribution-Share Alike 3.0 License. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License (MPLv2). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.