Re: [Libreoffice] Script to find undocumented classes

On Wednesday 01 of December 2010, Tor Lillqvist wrote:
> > After having years of experience using a nice, intuitive
> > and well-documented APIs (Qt,KDE),
>
> But surely you should realize the causality here? It is exactly your years
> of experience with them that makes Qt and KDE seem nice and intuitive.
>
> It is extremely hard, probably impossible, to come up with an objective way
> to indicate what is intuitive. As the old saying goes, the only intuitive
> thing (for a mammal) is the nipple. Everything else is learned.
>
> The same argumentation is seen over and over again in all areas of
> software... "I have used Photoshop for years, it is so intuitive, GIMP
> sucks." "I have used Windows for years, it is so intuitive, Linux sucks."
> (Intentionally just saying "Linux" here because people who make that claim
> hardly know which FLOSS desktop environment they are referring to.) "I have
> used Fortran for years, it is so intuitive for numerical programming."
>
> I am sure it is not hard to find people who think the OOo code APIs are
> elegant, consistent and intuitive. And they would be equally right.

 Well, no, sorry.

 First of all, while most of my experience comes from working with Qt/KDE, I 
usually worked on the lower level parts of it, making me often look at other 
software, be it libs like fontconfig, Xlib, polkit, or various non-KDE 
software. So I do have quite some experience figuring out unknown code.

 Second, I think it is possible to measure how good API/documentation is, to 
some extent. You can compare how extensively and well it is documented (sure, 
there are some exceptions like polkit being very extensively and rather 
unhelpfully documented, but generally it's rather hard to beat something like 
e.g. [1]). You can look at some code and see whether you can guess the 
meaning even without being familiar with it ("const SwFmtFrmSize& rLSz = 
pLineFmt->GetFrmSize();" - huh? I still need to decipher this one and I've 
been told the meaning at least 3 times). You can look at the documentation 
and see how quickly you find a way to do something you need. And so on.

 I'm not going to dwell much on showing that Qt/KDE APIs are easier to use, 
because quite frankly I find that obvious, you can just ask anybody around or 
try it yourself. They are simply designed that way and there are certain 
requirements, while it seems LibO doesn't have that. I may be biased because 
of familiarity, but the difference is simply huge. And BTW, [2] is a very 
interesting read.

 I don't mean to bash anybody for this, but this is simply the biggest 
impression with LibO that I have - that it's awfully difficult to get into 
it. The combination of massive codebase and poorly documented (and often 
cryptic) APIs is just overwhelming. I may have time to get over it, but does 
that mean we're not interested in those possible contributors who wouldn't 
have this much time and guidance? Speaking of which, since the opening of 
LibO, how many of those new contributors have contributed something that 
requires at least some understanding of the codebase (i.e. not counting dead 
code removal, comment translations or similar)?
   
[1] http://doc.qt.nokia.com/4.7/qstring.html
[2] http://doc.trolltech.com/qq/qq13-apis.html

> > So I find any suggesting that docs are not necessary (or valueing merging
> > higher) to be eventually shooting ourselves in the foot.
>
> Personally I think it would be very nice if source files had just a few
> lines of comment telling what they are about, from a very high perspective.
> Every time I am searching for the implementation of some functionality in
> the OOo/LO codebase, I find myself looking at source files with vaguely
> correct sounding file names (and vaguely correctly sounding class names
> inside), but no clue if it actually is what I am looking for.
>
> (Yeah, now that we have forked off the codebase, I of course should take up
> the habit of adding such a few comment lines every time I find out what the
> code in some particular source file does, especially in cases where one can
> easily be mislead and spend hours looking at irrelevant code before
> realizing...)

 I think that would be very helpful.

-- 
 Lubos Lunak
 l.lunak@suse.cz