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


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

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.