Lubos Lunak wrote:
On Tuesday 30 of November 2010, Thorsten Behrens wrote:Additionally, I think most classes don't necessarily need detailed docs for all methods in the first place (which may also hurt later merging from OOo), but would already benefit from a two-line "mission statement" at class level (of course plus some module-level overview of "what's inside").I beg to differ. After having years of experience using a nice, intuitive and well-documented APIs (Qt,KDE), and being used to that, I sometimes rather suffer getting familiar with this codebase. Most APIs are not documented at all (or at most poorly, or in German, which is about the same in practice for many people). This is futher made worse by some APIs not being very intuitive (cryptic abbreviations, unclear naming, obsolete idiosyncracies, duplication, basic things being needlessly complicated).
Hi Lubos, adding documentation for what you describe doesn't help much, if at all. Core API is reasonably documented, see offapi/udkapi/sal/basegfx. The most egregious cases of hard-to-grasp methods surely live in the applications cores, use lots of weird abbreviations - and to document their behaviour succinctly would prolly require as much prose as there's code already inside them (i.e. multiple pages). For me, a cleanly designed class with one and only one task (and a proper mission statement, maybe - superfluous even for something like "String"), does not need much method documentation. Suitably-chosen method names, especially if they don't take 10 parameters, and only work for exactly 42 combinations of them, are almost self-documenting. I simply refuse the notion that adding superficial documentation to crappy api gets us anywhere - which does not rule out storing hard-won knowledge of class purpose, inner workings, important pre- or postconditions at times - and if it makes sense, as method- or class-level doxygen documentation. But to really fix the problem you mention, I'm afraid only large-scale refactoring helps. And wrong documentation surely is worse than no documentation. (sorry for the rant, that struck a chord. Also, I'm clearly with you that larger parts of vcl & [sv]tools public headers are in dire need of method-level documentation. I'd even suggest to start there, that code does not change much) Cheers, -- Thorsten
Attachment:
pgpWN2uBEu88u.pgp
Description: PGP signature