Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

comment on

( [id://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":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (5)
As of 2024-04-19 07:17 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found