Nice writeup. ++ for that and for bringing this topic up.

But i have to disagree. ;)

Commenting is an art form - too much or too little can both be bad. IMHO, the following snippet uses unecessary comments: (update - except the ones marked with *, again IMHO) 

# open the file and quit if we can't *
open(FH,'foo.txt') or die $!;

# store the contents into an array *
my @line = <FH>;

# close the file
close FH;

# for each element in the array, print it *
for my $line (@line) { # start for loop
   # print it
   print $line;
} # end of for loop

# exit
exit;

[download]
But, for complex, obfuscated lines of code - you have to make comments for them! 
if (exists $self->{'pk'}) {
  $self->{'pk_index'} = delete $self->{'fields_hash'}->{$self->{'pk'}}
+;
  splice(@{$self->{'fields_arry'}},$self->{'pk_index'},1) if defined $
+self->{'pk_index'};
}

[download]
Say you wrote that piece of code five months ago. At the time, it made perfect sense - but now, you can't remember why you did that. That is why comments are good - to quickly jog your own memory so you don't waste time trying to remember.

jeffa

L-LL-L--L-LL-L--L-LL-L--
-R--R-RR-R--R-RR-R--R-RR
B--B--B--B--B--B--B--B--
H---H---H---H---H---H---
(the triplet paradiddle with high-hat)

In reply to (jeffa) Re: Commenting One's Code In A GNU/GPL/OpenSource World by jeffa
in thread Commenting One's Code In A GNU/GPL/OpenSource World by Revelation

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.