[Libreoffice] Script to find undocumented classes

[Thorsten Behrens]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/libreoffice/attachments/20101201/aed07049/attachment.pgp>