However, while coding the algorithm, there are almost always assumptions used and conclusions reached by the programmer. You've all had that while you're coding... those thoughts like "Oh, this could be undef here" or "We must ensure that @foo is initialized before getting here" or "This will work for small lists, but blows up on big lists."

That's what belongs in the comments. Capture those thoughts, so that someone else can recreate your insights.

First, the reader of the code three months from now isn't necessarily in the same brainspace as you, and may not realize the same assumptions.

Second, in three months, you will not be in the same brainspace either. Trust me on this one.

So, comments should capture the insights and presumptions. The code should clearly express the algorithm on its own.

Just a thought, from someone who has been programming for 30 years, including re-writing code of others far too often, and pounding my head against the desk saying "WHAT were they THINKING?" {grin}

-- Randal L. Schwartz, Perl hacker
Be sure to read my standard disclaimer if this is a reply.

I agree wholeheartedly.

I'd like to clear up one issue though...

My gripe comes as a long suffering maintenance programmer. Who, likewise, for the last nearly 20 years I have spent a great deal of time working on existing code covering many languages rather than the far less often 'writing shiny new stuff'. It's the comments in these old routines that I always view with suspicion.

---

'I think the problem lies in the fact that your data doesn't fit my program'.

------
We are the carpenters and bricklayers of the Information Age.

Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement.

Please remember that I'm crufty and crochety. All opinions are purely mine and all code is untested, unless otherwise specified.

I like to have one comment at the top of each file that says what the program or module is supposed to do. I also like to comment my bugs or poorly written code. I can tell that the code is okay when all of the comments are gone and I can still easily read the code.

If the code is a module that is intended to be used more than once, writing the pod documentation is still a good idea. This is different from code comments, though. If the module is well-written, it probably won't be subjected to cut-and-paste, it will get used properly.

It should work perfectly the first time! - toma

Yes, it's particularly difficult recovering from the situation where you were handed poorly-commented code. "Recovering" is about all you can do, retroactively. The solution is in working proactively when you get the chance to mold the minds of your successors.

I try to instill the following principle in new developers:

Put strategy in comments, tactics in code.

Another way to phrase this, though I think it's less strong, is "Comment why, code how." Comments should be an orientation to the general approach, not a roadmap to the use of the language and techniques used. Comments are for the maintenance programmer, who really doesn't want to STUDY your code, just surgically adjust it.

Enforcing the strategy/tactics metaphor also implies that you have to have a strategy before you can employ effective tactics. For a largish subroutine, start by coding the stub, with an English explanation of the approach to be taken. Under each line of comment, execute the tactics that will meet the strategy. Under "# Arrange unique entries", write the hash scanning and schwartian transform that achieves this aim.

Lastly, try to phrase your code so that it reads. One trick is to imagine trying to read your code aloud over the phone to someone else. Don't worry about using a few extra lines instead of a few extra clever operators. Don't hide the key conditionals that will control the routine. Be clear.

--
[ e d @ h a l l e y . c c ]

With well-written code, comments (which I consider seperate from the overall documentation, e.g. POD) are often unnecessary. For instance, probably all the CGIs I've written over the past year have a set_params() sub that (surprise!) takes in the CGI input params. It is almost always simply some form of:

use CGI qw(:standard);

sub set_params
{
   my %fields;
   $fields{foo} = param('foo') || 0;
   $fields{bar} = param('bar') || 0;
   $fields{baz} = param('baz') || 0;

   return %fields;
}
[download]

I used to mix in some validation, but I'm trying to force myself to do that in a seperate sub.

A maintenance programmer looking at the above can know exactly what parameters are being input. No comments necessary. Occasionally, there are some hoops to jump through, in which case a sprinkling of comments is needed.

POD, IMHO, is for telling what the overall program/module does. Which is why I don't really like the =for comment method of multi-line comments.

Having a boatload of comments is a good indicator of poor code. Hint: if I have to run your code through B::Deparse just to get rid of your comments and save my sanity, your code probably sucks. Those thousand-dollar "source code obfuscation" tools have got it all wrong--leaving massive numbers of comments in place is a great way to protect your source code :)

----
I wanted to explore how Perl's closures can be manipulated, and ended up creating an object system by accident.
-- Schemer

Note: All code is untested, unless otherwise stated

# Check each element of the array vs. the supplied pattern.
[download]

# Eliminate items that can't be processed.
[download]

It is true that in other people's code you will sometimes (for larger and smaller values of "sometimes") find code and comments that don't match, or useless comments like those above.

If you are responsible for the maintenance of the code, it is your responsibility to not only fix any bugs, but to make the comments useful. This will consume a little more time, but you will have recorded a solid foundation to work from when you (or the next person) come back to the code later.

Having added comments that are accurate to the best of your ability to understand the code, even if the comment is

# XXX I can't tell what this next section is doing.
[download]

It is always your responsibility to comment your own code in the most useful manner possible; if you must cut and paste, at least indicate that you did so and add a comment saying what you intended to achieve.

(This is based on my experiences in coding and in attempting to usefully recomment perl5db.pl).

Over the course of 25 years slinging code, my answer is "less and less." I've been burned too many times by elaborate commentary that had little relation to the "truth" of what the system was really doing. Commentary rarely survives program growth and maintenance.

The commentary I tend to trust are "what does this do?" comments, if they're brief. The larger the comment, the less I tend to trust it. I also pay a lot of attention to "BUG", "FIXME", and "TBD" comments, though conceptually these are more like Post-It markers in the code.

POD is really something different. It's external documentation that's been entwined in the code.

Hear hear! My trust in the comments depends on who wrote the code. I know programmers who cannot be trusted with snake control in Ireland who are also prolific commenters. This should be no surprise; it seems thatthe less people know, the more they talk to prove they know something. (Of course, they usually prove the opposite ...)

--
tbone1
Ain't enough 'O's in 'stoopid' to describe that guy.
- Dave "the King" Wilson

Hello, my name is Nkuvu, and I'm addicted to comments...

I'm a prolific commenter, particularly in Perl. But I also know that I have to maintain the comments (usually) more often than the code itself. And it should also be noted that the people who are reviewing my code aren't Perl proficient. So I comment Perl-specific operations, to help the reviewer see what I am doing -- why is usually obvious (but documented if not). For example, if I have ($foo) = $bar =~ s!\\!/!g; I'll comment on it. Because you don't see things like this in C/C++.

It was also hammered into me throughout my university career that comments are good, lack of comments is bad. Period, no flexibility in that conclusion. But I can see all of the points that other monks have made, and resolve to comment less in the future. Most of my code is very similar to C/C++, due to the people I'm working with. And I can't assume that the person who maintains my code will be a Perl programmer.

When I started with Perl, it was to update a script written by a no-longer-present programmer. He had very poor style, with variable names like $l (that's an ell) and $x throughout the script. I could have killed for comments in his code, especially since I didn't know Perl. So I've kind of overcompensated since then.

I suppose I shouldn't admit that one of my scripts (which has a complicated algorithm) is over 50% comments...

It sounds like you think comments are there to benefit people who are new to programming, or at least new to Perl. The problem is that these types of comments are incredibly distracting once you actually know the language, and at that point they just take up valuable screen real estate that could be filled with code. In most development situations, you should assume that the next person to read the code will be reasonably competent. If not, they have bigger problems than just dealing with your program

I disagree - I comment heavily on what I was thinking at the time. It has little to do with the actual code, and more to do with intentions:

# we know this is coming from XXX because of sub xxx, so we don't need
+ an extra taint check here
[download]

etc. I can go back to code I wrote only a week ago that I've already forgotten (small buffer :) and have trouble going through it quickly unless I do this.

But then. maybe I'm just dopey :)

.02

cLive ;-)

To tell the truth, I never really considered why I should add comments. It was just drilled into my head that I should.

And once I start thinking about why I should comment things, I can see that I've been going about it all wrong.

The only text that I like to make is the POD for the module, explain how to use. But explain why I made some XS like that, etc... not. Is always better read all the code and understand it, and I never read the comments, they are alway bad, or is easier to understand the code.

The best comment that you can make are names that make sence for variables and functions/methods (sub). And of course, use a structure/flux for your code that make sence too.

Graciliano M. P.
"The creativity is the expression of the liberty".

I tend not to trust comments. I much prefer good unit tests, assertions, well factored code, preconditions, postconditions, etc. "Executable comments" have the huge advantage that they cannot get out of sync with the code.

One of the many things that intrigue me about perl6 is that things like .wrap, POST, PRE, typing, etc. make this sort of documentation-in-code far easier.

Favourite comment of all time, which once lived in the guts of a large system I worked on for a few years, was :

;;; I don't understand why this works?
[download]

Since the customers had access to the source this was removed at the request of some management when it was noticed. The code it sat above wasn't refactored tho' :-)

You might also find Documenting Methods/Subs of interest.