I couldn't agree more about commenting and how important it is.

I have two rules that I follow no matter what I code, unless I'm going for a one-line wonder.
  1. Comments should say why you're doing something, not what you're doing something
  2. You're never coding something for yourself, but for the coder who will be maintaining it in the future.
These are both incredibly important in my methodology of coding. Unless I'm writing bizarre (or obfuscated) code, I can usually tell what I'm doing with the code. It's not a matter of what I'm doing, but why I'm doing it. Someone mentioned that in a prior response, but they said both what and why, whereas I feel that a "This code does X" comment isn't terribly worthwhile unless there's a reason why you're doing that - and then it's worthy of a comment.

Also, writing code for those who come after you is very helpful, as it keeps people from bugging you with questions about code you've moved on from. ;) A good example of this would be my current position. I've written code that (hopefully) will never have to be updated or maintained. However, that's just a pipe dream. So, since the people who will be coming after me have no Perl experience (cause my boss insists on hiring people with no PC knowledge but with people skills <rolls eyes>), almost every single line of my code is commented with why I'm using a chunk of code there.

Comments are one of the best tools a coder has - use them wisely. :)

~Brian

In reply to Re: Why I'm a Pod::Nazi by brianarn
in thread Why I'm a Pod::Nazi by Bobcat

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, details, 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, summary, 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.