Re: Code documentation trends

On Thu, 2007-08-16 at 10:21 +1200, Amos Jeffries wrote:

> What I'm hoping for is to have a paragraph for each class about where its
> intended to be used etc.

That would be terrific! I was trying to provide that for the classes I
was adding.

> Theres lots of little bits still need doing for the Mem component.
> You can see what it looks like at:
> http://squid.treenet.co.nz/Doc/Code/MemPool_8h.dyn#2eab9a6fa490ed842eeee6a1800e0ec4
>
> I think maybe it's the text-description not making it clear its a
> code-example. That description needs fixing.

Yeah, I can hardly grok the current doxygen rendering.

Said that, I care more about how .h looks, and the change makes it look
"worse", IMO. Perhaps it will all be much better after the next round of
"fixing", but I fear that I will spend more time trying to find and
understand things before the doxygen invasion.

But again, this is not a huge deal.

> > None of these changes are a big deal, of course. I am just worried about
> > the general trend of hiding code behind overly verbose documentation...
> >
> > Does doxygen support some kind of \include mechanism where verbose
> > documentation can be moved away from the code while still being linked
> > to specific code pieces? Detailed documentation is great, but if it
> > makes the actual code difficult to see, it is doing more harm than good,
> > IMO.
>
> Yes, but that defeats the entire purpose of this project. Having the
> documentation at the point of code where it will get noticed for change by
> any average-joe editors altering that code. I don't expect it to be huge.

Yes, I understand the motivation, but every solution taken to the
extreme becomes a problem. For example, it would be clearly
inappropriate to explain what a C++ class means or how a C++ macro works
next to every (or any!) Squid class or macro declaration. Similarly,
inserting a chapter on Squid performance optimization next to StoreEntry
declaration is wrong.

Overly verbose comments are almost as bad as the missing ones. We should
not forget that correct, maintainable _code_ is the primary goal. Good
code should not require many verbose comments. And too many verbose
comments obscure good code.

Again, these are general trend-setting observations. The specific
example that prompted me to write this is not the most extreme case of
verbosity.

> I've had a hard time converting the SGML because it references only 2.5
> examples and function names, describing how they behave in 2.5, and had to
> check each function operation and change some of it in migration.

Sure. And there are lots of obsolete comments in Squid _sources_ as
well!

Alex.
Received on Wed Aug 15 2007 - 22:30:46 MDT