Doxygen Code Documentation

[Derek Atkins]

John Ralls <jralls at ceridwen.us> writes:

> Some programmers, often less-experienced ones, will comment code
> liberally to explain what they’re doing. More experienced programmers
> often find this irritating because they’re fluent enough in the
> programming language that they can understand the code without the
> comments and the comments just get in the way. Those programmers
> prefer a brief descriptive comment only when the author finds it
> necessary to do something non-ideomatic.

I dunno; I consider myself an experienced programmer and I like
documenting my algorithms (to explain how chunks of code work).  I don't
necessarily comment each line (e.g., I wouldn't be in a comment
"increment x" next to or above "x++;") but I do like to, even 10-20
lines or so, put in a comment about what the block of code is supposed
to do.

If nothing else it helps me when I revisit the code a year later to get
myself back into the mindset, otherwise I wind up going "what was I
THINKING when I wrote that?"

> None of which should be taken as a defense of GnuCash’s code or API
> documentation. A lot of the code is a turgid, unideomatic mess with
> several-hundred-line functions calling all over the place and
> sometimes flipping back and forth between Scheme and C. Writing bug
> reports about it won’t be helpful unless you submitting a patch, and
> then only if it’s a good patch that improves code readability,
> testability, or Doxygen documentation. If that’s the sort of work you
> want to take on, Welcome! If you haven’t already, get a copy of Martin
> Fowler’s “Refactoring” and study it: It’s the bible for fixing ugly
> code.
>
> Regards,
> John Ralls

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available