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
Attachment:
pgprtQoMF43to.pgp
Description: PGP signature