Comments serve to communicate from the person who knows how the code works (you, now) to the person who doesn't (you, or someone else, later). They are an investment, and a big part of the trade-off is how long the code will be around, and how much you care about the time and effort of the person who will read the code (maybe you).

Nothing beats clear and elegant organization and good names for functions and variables. Some people are skilled at that and naturally remember to do it. Some aren't and don't. Mandated function comments serve to help the latter. They are a reminder to think about how to communicate, rather than just how to do get the computer to do the job at hand. If the clarity of GrandGather's code here at PM is any indication, he probably doesn't need that. I need the extra step. Often I end up with no function comment, but I've changed the name of the function to something more informative. It's nice when what one needs to know at a glance fits well in the function name. When it doesn't, a function comment is a great help.

Function comments can also provide an outline structure, like section headings in a book. When I'm going back to find something in "Perl Best Practices", I can find it more easily because there's a brief rule summary right below the section title. I don't have to read the whole section and the supporting arguments to be reminded what the rule is. Similarly, in 

# Accumulate and print YTD total, recording updates to disk.

sub PrintYTD {
...
}

[download]
The comment helps me see what's done here, without reading the part where I set permissions on the new, updated monthly-total file, having renamed the previous file as a backup. Writing the comment may also prompt me to move writing of monthly totals somewhere else, or leave a TODO for a time when such a change can be adequately tested.

So for me, comments make for better code, both as a prompt for thinking about how the code communicates to people, rather than the compiler, and as an outline structure.

In reply to Re^2: Are there any drawbacks to comments -- can they hurt the performance of Perl code? by rodion
in thread Are there any drawbacks to comments -- can they hurt the performance of Perl code? by jira0004

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.