Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

Re: Programming *is* much more than "just writing code".

by GrandFather (Sage)
on May 08, 2007 at 21:42 UTC ( #614255=note: print w/replies, xml ) Need Help??

in reply to Programming *is* much more than "just writing code".

It seems to me that there are two programming modes: green fields and maintenance, and that their commenting requirements are different. In the green fields mode I emphatically agree with the assertion that less is better wrt comments. However, in maintenance mode comments are often the most valuable contribution to the code that you can make for a number of reasons:

  1. to correlate a bug with a code change
  2. if today's maintainer needed large effort to understand the code so most likely will tomorrow's
  3. a maintainer is often better placed to see where a comment provides the most bang for a buck
  4. (sometimes) to distinguish a maintenance change from original code
  5. (sometimes) to elucidate the maintainer's understanding of the code

That is not to say that every changed line of code requires a comment or that every comment should be a story that includes the maintainers state of mind and how much coffee had been consumed. The rules for succint and sparse commenting still apply but the bar is lowered somewhat in light of a need to compensate for deficiencies (perceived or otherwise) in the original code. The alternative may often be a completely impractical refactorisation of the code.

If a back story is required for the code changes, that should be in the bug tracking system with a synopsis in the check in comment in the revision control system.

If even half an hour is spent trying to understand a section of code, and that investigation could be averted in the future by addition of a brief comment, then the comment is a good investment. Most times just a couple of words is enough to provide the hint required for understanding. Anything more than a few words should point to documentation elsewhere - five minutes reading documentation is still way better than a half hour investigation.

Non-trivial bug fixes require a higher degree of commenting simply because, if the issue wasn't obvious to the original programmer, it probably won't be obvious to whomever follows.

Very nice node btw!

DWIM is Perl's answer to Gödel
  • Comment on Re: Programming *is* much more than "just writing code".

Replies are listed 'Best First'.
Re^2: Programming *is* much more than "just writing code".
by BrowserUk (Pope) on May 08, 2007 at 22:23 UTC

    I agree with you on this, in every detail. Especially if the maintenance programmers comments are of one of the following forms:

    • ## See rt #1234
    • ## See perlmonks node: 123456
    • ## See change log item buk 08-05-2007
    • ## A new element (TIME_OF_DAY) was added to the array
    • ## See file DB_object for a description of the elements of the array
    • ## The data is denormalised (fields are duplicated) for efficiency.

    That's just a few that come to mind.

    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.
Re^2: Programming *is* much more than "just writing code".
by jplindstrom (Monsignor) on May 09, 2007 at 14:43 UTC
    Well, green field projects usually enter maintenance(ish) mode fairly quickly, usually somewhere between three and six months in.

    This isn't a bad thing, but rather a fact of life and so should be embraced and dealt with.

    If they don't take on a more maintenance kind of style, it is because of a lack of one or more of:

    • Short iterations (shorter than a month)
    • Proper testing (and the resulting lack of code quality feedback)
    • Deployment, or at least decent show-and-tell sessions with the stakeholders (and the resulting lack of design and requirements quality feedback)


Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://614255]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (7)
As of 2020-10-27 22:00 GMT
Find Nodes?
    Voting Booth?
    My favourite web site is:

    Results (258 votes). Check out past polls.