Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

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

In reply to Re: Programming *is* much more than "just writing code". by GrandFather
in thread Programming *is* much more than "just writing code". by BrowserUk

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others chilling in the Monastery: (4)
    As of 2020-10-28 00:44 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      My favourite web site is:












      Results (259 votes). Check out past polls.

      Notices?