in reply to Commenting One's Code In A GNU/GPL/OpenSource World

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)

Replies are listed 'Best First'.
Re: (jeffa) Re: Commenting One's Code In A GNU/GPL/OpenSource World
by cjf (Parson) on Mar 31, 2002 at 19:16 UTC
    Commenting is an art form - too much or too little. IMHO, the following snippet uses unecessary comments:

    Well said. Excessive use of comments can be just as annoying as a lack of comments. I'm sure almost everyone will agree that the snippet you posted was overcommented, however someone just starting to learn Perl might find it useful (many tutorials also use this format). The tricky part is striking a good balance so your code remains useful to the most people.

[reply]

In Section Meditations