On Perl :: Index

The point of a comment is to do nothing, so what good are they? Well, you might be surprised. Firstly they are an invaluable form of documentation. If you're trying to work through a complicated process start with comments.

# for each file on the command line...
# while it has lines to read
        # find and print if starting with "#"

Then fill in the code to do what the comments describe.

#!/user/bin/perl

# for each file on the command line...
# while it has lines to read
while (<>) {
        # find and print if starting with "#"
        print if /^\s*#/;
}

Run this file on itself to get the comment-only version back again. This isn't the usual way to write code, but if the complexity of a problem is in simply defining the steps, this can be a valuable way to start. Good comments describe the purpose of the code they accompany. Have a look at some comments in CPAN code and you might see some interesting things. For example, secrets might be revealed, as in CGI-Untaint-html-1.0, where Simon Cozens confides...

# I'll tell you a secret. Modules I write get version 1.0 automatically
# if I've ever used them. If they're 0.x, I've never actually used them
# myself.

But sometimes a comment can be perfectly useless, as in WebSphere-MQTT-Client-0.01...

# Return 0 if result is OK
return 0 if ($result eq 'OK');

And if you'd just installed Perl6-Classes-0.22 into your production codebase, you might be alarmed to read this comments tucked away inside the source...

# This whole file is a pile of ascii feces.

But comments have other uses to. An invaluable one is during debugging. If you are having trouble with a section of code but aren't sure exactly where, you can zero in on the bug by commenting sections out. But don't waste time typing and deleteing hash marks, use Perl's multiline pod-comments...

=for comment

$this->is(ignored);

=cut

A more sopisticated use of comments for debugging is Damian Conway's module Smart-Comments. While this module is in effect comments that start with the tripple-hash "###" become executable. Add informative debugging messages to these comments then simply turn "debugging mode" on or off by commenting in or out the use of the ,a href="http://search.cpan.org/~dconway/Smart-Comments-v1.0.2/lib/Smart/Comments.pm">Smart-Comments module.

#!/user/bin/perl
use Smart::Comments;

my $x = 1; ### x is set to $x

Finally, if you don't happen to like Perl's comments then have a look at Jos Boumans' Acme-Comment module which allows you to write comments in other languages. It supports the syntax of a very wide variety of languages.

#!/user/bin/perl
use Acme::Comment type=>'HTML';

$x = 1;
<!-- this is a comment -->

A Few Comments on Comments