On Mon, May 19, 2008 at 08:42:49PM +0300, Octavian Rasnita wrote:
> By the way, what do you think about the following commenting style:
>
> q/
> the
> commented
> lines
> /;
>
> It is a valid perl code, and it only gives a warning if "use warnings" is
> used, but it is not a problem because we know that this scalar is used in
> scalar context not because there is an error, but because we want this.
In which case you should turn off the warning, in the smallest possible
scope.
> And it is much shorter than the POD syntax.
Which sort of invalidates that argument.
Not turning off the warning is bad because of the broken window effect.
Keep your code clean. Turning off warnings for longer than is needed,
or completely, is bad because you are working without a safety net.
Also, consider
sub half
{
my ($val) = @_;
$val / 2;
}
Now, your new company coding standards say that you need to add a
comment to each sub saying what it returns, so you dutifully add
sub half
{
my ($val) = @_;
q/
Returns $val / 2
/;
$val / 2;
}
Oops, that was confusing. So, after working out what that error message
means, you change things a bit:
sub half
{
my ($val) = @_;
q/
Returns $val divided by 2
/;
$val / 2;
}
Ah, much better. But then the coding standards say that this comment
should be at the end of the sub, just after the thing being returned.
sub half
{
my ($val) = @_;
$val / 2;
q/
Returns $val divided by 2
/;
}
Eek. All your tests start failing. You have tests, right? Otherwise
your customers start calling you up in the middle of the night after
installing your latest release. And in your semi catatonic state you
don't notice anything because you are used to seeing a warning on that
line. Or worse, you have turned off warnings there.
A little contrived? Probably. But I guarantee that something weird
will happen if you take this route.
No, the real solution here is not to try to shoe-horn multiline comments
into a language which doesn't support them. The solution is to prefix
each line of comment with a hash (#). A decent editor will be able to
make this a painless process.
But what about commenting out half a page of code which may already
contain real comments? That one's simple. Don't do that. Comments are
for words, not code.
If the code is not needed, delete it. If you're not sure and think you
might want it back again later, that's what your version control system
is for. Or in the shorter term, your editor's undo feature.
Mutliline comments: Just Say No!
--
Paul Johnson - [EMAIL PROTECTED]
http://www.pjcj.net
--
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
http://learn.perl.org/
