Re: Doxygen Code Documentation

[Matt Graham]

Thanks for responding so quickly guys!


FYI John, I’m not planning on commenting line by line - just commenting all the methods/variables/structures so that people can see how things interact whilst browsing doxygen pages. I’ll try to get around to reading your recommended book, but it probably wont be for a few days.


I like Derek's idea of commenting blocks of code, but I'll probably only do this for areas that look really hard to understand (and probably more for myself than for submission).





Thanks and regards,

Matt Graham





From: Derek Atkins
Sent: ‎Tuesday‎, ‎1‎ ‎September‎ ‎2015 ‎01‎:‎13‎ ‎
To: John Ralls
Cc: Matt Graham, gnucash-devel at gnucash.org





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