/ 
Perl-Critic-Pulp-73
River stage two • 5 direct dependents • 13 total dependents
/ Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline

NAME

Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline - comma at end of list at newline

DESCRIPTION

This policy is part of the Perl::Critic::Pulp addon. It asks you to put a comma at the end of a list etc when it ends with a newline,

@array = ($one,
          $two     # bad
         );

@array = ($one,
          $two,    # ok
         );

This makes no difference to how the code runs, so the policy is under the "cosmetic" theme (see "POLICY THEMES" in Perl::Critic).

The idea is to make it easier when editing the code -- you don't have to remember to add a comma to a preceding item when extending or cutting and pasting lines to re-arrange.

If the closing bracket is on the same line as the last element then no comma is required. It can be be used if desired, but is not required.

$hashref = { abc => 123,
             def => 456 };   # ok

Parens around an expression are not a list, so nothing is demanded in for instace

$foo = (
        1
        + 2        # ok
       );

But a single element paren expression like this is treated as a list when it's in an array assignment or a function or method call.

@foo = (
        1
        + 2        # bad
       );
        

@foo = (
        1
        + 2,       # ok
       );

Return Statement

A return statement with a single value is considered an expression so a trailing comma is not required.

return ($x
        + $y    # ok
        );

Whether such code is a single-value expression, or a list of only one value, depends on how the function is specified. There's nothing much in the text (nor even at runtime) which would say for sure.

It's handy to included parens around a single-value expression to make it clear some big arithmetic is all part of the return, especially if you can't remember precedence levels very well. And in such an expression a newline before the final ")" can help keep a comment together with a term for a cut and paste, or not lose a paren if commenting the last line etc. So for now the policy is to be lenient. Would an option be good though?

BUGS

Is a return statement an expression or a list?

return (1
        + 2
        + 3    # should this be ok, or not?
       );

Strictly speaking it would depend whether the intention in subr is a list return or a single value, where there's no way to distinguish. Perhaps it should be allowed if there's just one expression.

Disabling

As always if you don't care about this you can disable RequireTrailingCommaAtNewline from .perlcriticrc in the usual way (see "CONFIGURATION" in Perl::Critic),

[-CodeLayout::RequireTrailingCommaAtNewline]

Other Ways to Do It

This policy is a variation of CodeLayout::RequireTrailingCommas. That policy doesn't apply to function calls or hashref constructors, and you may find its requirement for a trailing comma in even one-line lists like @x=(1,2,) too much.

CONFIGURATION

except_function_calls (boolean, default false)

If true then function calls and method calls are not checked, allowing for instance

foo (
  1,
  2     # ok under except_function_calls
);

The idea is that if foo() takes only two arguments then you don't want to write a trailing comma as it might suggest something more could be added.

Whether you write calls spread out this way is a matter of personal preference. If you do then enable except_function_calls with the following in your .perlcriticrc file,

[CodeLayout::RequireTrailingCommaAtNewline]
except_function_calls=1

SEE ALSO

Perl::Critic::Pulp, Perl::Critic, Perl::Critic::Policy::CodeLayout::RequireTrailingCommas

HOME PAGE

http://user42.tuxfamily.org/perl-critic-pulp/index.html

COPYRIGHT

Copyright 2009, 2010, 2011, 2012 Kevin Ryde

Perl-Critic-Pulp is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Perl-Critic-Pulp is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Perl-Critic-Pulp. If not, see <http://www.gnu.org/licenses>.