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
