Acme::Comment
Multiline Commenting for Perl
by Jos BoumansAugust 13, 2002
/*
This is a Perl comment
*/
Commenting in Perl
"But what?", I hear you think, "Perl doesn't have multi-line comments!"
That's true. Perl doesn't have multiline comments. But why is that? What is wrong with them? Mostly, it is because Larry doesn't like them, and reasons that we can have the same effect with POD and Perl doesn't need Yet Another Comment Marker.
To illustrate, here we are at YAPC::America::North 2002, held in beautiful St. Louis. The weather is warm, the sun is shining, the sights are pretty and the beer is cold. In short, it's all things we've come to love and expect of a Perl conference. It's thursday, the conference is winding down and Siv is having a barbeque at his house. So a few of us end up in a car, headed to the barbeque. Uri Guttman is driving -- you know, the Stem guy -- with myself riding shotgun, and Ann and Larry in the backseat.
|
Related Reading 
Perl in a Nutshell, 2nd Edition |
It's a friendly chatter and from one topic, it goes on to another. And at one point, Perl6 is being discussed. Ann is asking questions about the new operators, techniques and generally how shiny Perl6 will be. And there, Larry explains us new and wonderous things. Some already mentioned in the apocalypses, some still ideas waiting to become firm concepts. And granted it does sound good, very good... even if they are taking away my beloved arrow operator. Then, a question comes to mind, and I ask: "So Larry, tell me, does Perl 6 have multiline comments?"
All I hear from the backseat is some grumbling and the 2 words: "use POD!";
Needless to say, the tone was set, and I didn't see nor speak to Larry all evening.
Multi-line comments emulation in Perl
But I disagree. I think multiline comments are good.
I hate tinkering with the # sign and the 80 character-per-line limit; I write a comment over a few lines and prefix each with a #. Which of course means inserting a newline.
Then I need to add a few words in the comments. The line becomes longer than 80 characters. I need to add another newline. And add a new # sign. Remove the former # sign. And now nothing is aligned anymore and I need to redo it. *sigh*
And apparently I'm not the only one who has had a gripe with this. It's been a consistent request for change through out the development of Perl 5, and here's a post on Perlmonks discussing exactly this
The idea is to find a way of doing multi-line comments in Perl, without breaking things. These are the four solutions they came up with to do multi-line comments, and why I think they are bad:
1. Use POD.
For example, you could use:
=for comment
Commented text
=cut
It's POD. POD is documentation for users of your program. Pod is not
meant to display things like 'here i change $var' or 'this
part will only be executed if $foo is true, which is
determined by some_method()'; More over since the part you are
commenting on is not in POD format, it won't be displayed in the
first place. This will mean that the comments would be displayed in the
POD, but the piece of code they refer to, will not be. Granted, most POD
parsers are smart enough (or dumb, depending on how you look at it) that
they see that the =for is not something valid and ignore
it, whilst the Perl interpreter will say 'hey, it starts with
=, so it must be POD'; In the end, if you have the 'proper'
POD parser, you will get sort of what you want.
But you are really circumventing the problem here, since you are relying
on the way any given POD parser parses POD; some might 'use warnings'
and report an invalid =for tag on some lines. Others will
just display them.
And what we wanted was a way that would allow multi-line comments without possibly breaking things.
2. Any decent editor should allow you to put a # in front of n lines easily...
That's not an answer. We wanted multi-line comments, not an editor trick that allows me to do multiple single-line comments. That and I'd rather not get into the 'vi is better than emacs' flamewar ;)
3. use HERE-docs
<<'#';
this is a
multiline
comment
#
<< '*/';
this is a
multiline
comment
*/
This works, if you remembered to put a newline directly after the end marker. Well, more accurately: it parses correctly. It's a here doc, that means that variables WILL get interpolated if you use a double quoted string.
Meaning if you do something like this:
use strict;
<<"#";
this is a
multiline
comment
about $foo
#
It will blow up right in your face with a compile time error. Also,
when running under 'use warnings' --which you should-- this will
generate a 'Useless use of a constant in void context at foo.pl
line X' warning.
So not completely foolproof. Plus it looks ugly ;)
4. use quote operators
q{
some
comment
};
Ok, a much more rigid solution and much more elegant. Does it work? Yes.
Well, almost. It runs under strict. But I didn't expect anything else, since the guy who posted this (juerd) is an experienced Perl hacker and probably knows what he's doing. But it does cast warnings, just like the previous HERE-doc solution:
'Useless use of a constant in void context at foo.pl line X'
Now, your comment is supposed to be there to help other coders, not to be generating warnings. It's a NO OP! It shouldn't make them think things are going wrong!
Pages: 1, 2 |
