Re: [Libreoffice] Script to find undocumented classes

On Wednesday 01 of December 2010, Thorsten Behrens wrote:
> 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.

 The first line looks true, but the rest is from a superhuman, because for us 
mere humans documentation does have a value, even if the code would be 
perfect. It's mostly because we happen to be mere humans and do not have the 
brain capacity to remember everything or the time to analyse everything in 
detail. Documentation (and that is not just comments, but also API docs for 
example) is, if nothing else, a time-saver.

 To have a real example, see the sub-thread following 
http://lists.freedesktop.org/archives/libreoffice/2010-December/003756.html . 
Three developers, two of which I think quite highly of (I don't know 
Mattias), in a row failed to use properly a primitive class and ended up 
using a hacked up solution, because the moron that created this class saved 
at most few minutes by being too lazy to add at least "use 
SwCursor::RestoreSavePos()", eventually leading to much more time wasted and 
suboptimal code.

 A frustration-saver too, now that I think of it. I certainly had one of those 
WTF moments when trying to figure the problem out.

> 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.

 Have you actually ever worked with well-documented codebase? I can assure you 
that I've spent much more time reading API documentation of KDE library code 
(and saving me ever more time figuring it out myself) than I have spent 
writing it for my KDE library code (which is a non-trivial amount).

> 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.

 I see. Yes, your point maybe is extreme, because to me it looks like you're 
saying that documentation should be perfect and nothing less should be 
accepted, so if it can't be perfect, it has to be none, which will keep 
people clueless, so they at least won't touch the code.

> 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!

 Sorry, but you really do not understand what I am actually talking about. I'm 
not asking for anything ridiculous like having a paragraph explaining every 
line, I'm saying that everything non-trivial should have at least some 
documentation (or that should be at least goal, I don't expect everybody to 
start documenting everything today and dropping all other work). It is no big 
deal to require this for new code and whenever somebody runs into a problem 
or just feels like writing it down. KDE libraries are required to have this 
for all public API and nobody has a problem with that, and, just as well, it 
would be pretty unusual for 3 developers to fail using a class with just a 
ctor and a dtor.

 As for documentation getting out of date, especially when it's API 
description or code comments, I generally consider those getting obsolete 
being because the developer causing them was a moron who either broke public 
API or just quickly hacked up something without thinking about it.

 And even if that happens, I disagree with obsolete docs being worse than no 
docs - even wrong docs can help if you have a problem, you can search the 
history or similar, while without docs you're simply on your own and that's 
it.

 You know, if, after figuring out all these things about QuickFormatDoc(bool) 
and, you at least wrote down "the bool argument probably means that 
<whatever> but it has a lot of side-effects", you would very likely still 
have helped Sebastian a lot. Even that counts, nobody wants a load of prose 
from you.

> 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. ;)

 Good. I'll consider that mitigating consequences, so I will not suggest to 
Kendy to punish you with having to work with Qt-based code for a while :). 
That, of course, on its own wouldn't be a punishment, but that could come 
after getting back.

-- 
 Lubos Lunak
 l.lunak@suse.cz