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@gnucash.org
John Ralls <jra...@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
warl...@mit.edu PGP key available
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
