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]

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]

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)

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.

Commenting code sacrifices the educational purpose of code for maintainability and laziness.

I'd have to disagree. Commenting code makes it easier to understand, and in doing so, makes it easier to learn from.

First of all, if someone new to Perl who is looking for some code to learn from comes across your code and sees no comments, do you think they'll even bother trying to figure out what it does? If for some reason they do, they might end up making wrong guesses and coming to false conclusions. Including comments will make reading your code less intimidating and give people a basic understanding of your code which they can build upon.

The other side of it is that maintainability is important in publically released code as well. If you want your code to be truly useful to others and want them to reuse it, it needs to be well documented. This is especially important for larger projects.

Taking out the comments from your code will lead to code that is harder to maintain and is less useful to others. Even if comments did have some magical effect making all code with them uneducational, why not let people decide for themselves whether or not they want to take the comments out?

-Il Cylic

If you don't want code comments to explain *what* the code is doing, that's fine. If you object to comments that explain *why* the code exists, that's silly.

This past week, I've been bugfixing a pile of code best described as "misguided". It features the same dozen lines of code repeated thirty times, with different category names.

There's a purpose to the repetition. It's not a good one, but there was a reason for it. Since there were no comments, I had to read the original programmer's mind.

Good luck.

Or to coin a slogan: "It's easier to read the programmer's mind if the programmer writes it down." :)

stephen

• The purpose or purposes of the code is still unclear in the developer mind, that is it is in very early stages. Commenting at this stage *can* influence someone into thinking that is all or only what the code can/should do.
• I see over and over again, and I say it myself, that at some point in the future you will come back and look at the code and have to wonder what you did. I have to wonder if it is possible to influence your own corrections by reading your previous comments. I feel it is and I think it has even happened to me.
• Skill level of the intended audience. Not commenting can be a way to keep (scare) "unskilled" people away from the code, this has its advatanages and disadvatages depending on whether you want your project to used for new coders to learn from or if you are producing something delicated and by not commenting hope to keep the casual user from "hurting" themselves.
• My favorite reason (excuse): You have become enlightened and your knowledge of the code exceeds your impatience so commenting becomes a hinderence not an aid.

As I read it, your argument is based on two premises which don't necessarily (or even usually) hold:

1. Open-source code's primary purpose is to help programmers learn.
2. Comments hinder the learning process, because they give away information that would be better learned the hard way.

To the first premise: IMHO, open-source code is made open-source mostly to give people good tools that they otherwise wouldn't have access to, and if the code does mostly what they want it to, to give them the chance to modify it to do exactly what they want it to. If they learn something in the process, that's great, but the point is accessibility. So if you make open-source code harder to modify (by taking out the comments, for instance), you're defeating part of its purpose (the easy-to-modify bit).

To the second premise: depends what you want to teach. I'm going to learn more, and faster, about the language, or other back-end libraries, if I have to dig through the documentation to figure out how stuff works. On the other hand, if I'm trying to learn an algorithm, I don't want to get tied down to the details of just how each step works, because I'll lose the forest for the trees.

I don't think your argument's necessarily wrong, just a bit broad in scope. And thanks for bringing it up; I've enjoyed reading this thread.

--
:wq

Should we infer from you first paragraph that GNU/GPL/OpenSource code shouldn't meet professional standards? Do you feel that the genius of your contribution outweighs any responsibility for professional standards?

If you don't want morons to hack your code, don't put it where they can get to it. Do you really think morons won't "defile" your code just because they don't understand it or you don't comment it?

I think it is commendable that you want to save coders time and educate perl scripters. But educate them in what, the art of obfuscation? If you want to educate them, show them code that is as well documented as it is coded and useful.

--Jim

Hear! Hear! This Saint is totally correct! If there were a ranking higher than Saint, he'd certainly earn it. It appears that Revelation does not want to be criticized. After all, he was (at the time) just a high school freshman, relatively new to Perl, so one cannot judge him too harshly. But why would he post something so "elitist" if he's not an elite? Not to sound trollish, but Revelation's elitist views seem only to reflect his ignorance and fear that he will be downvoted. I never posted anything on any math or physics forum (subjects which I know somewhat better than programming) because I'm not a professional mathematician or physicist (yet.) I'm certainly not an ignoramus, and neither is Revelation, but I know better than to post a node implying that I'm just a student. Revelation had better heed the advice of his superiors. I'm sure he doesn't want to be known as the Worst Nodes (or Codes) Upvoter any longer than he has to! -100104