NAME

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

DESCRIPTION

       This policy is part of the "Perl::Critic::Pulp" add-on.  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 low severity and under the "cosmetic"
       theme (see "POLICY THEMES" in Perl::Critic).

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

       If the closing bracket is on the same line as the last element then no comma is required.  It can be be
       present 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 instance

           $foo = (
                   1
                   + 2        # ok, an expression not a list
                  );

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

           @foo = (
                   1
                   + 2        # bad, list of one value
                  );

           @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 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.  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 lenient.  Would an option be
       good though?

   Here Documents
       An exception is made for a single expression ending with a here-document.  This is slightly experimental,
       and might become an option, but the idea is that a newline is necessary for a here-document within parens
       and so shouldn't demand a comma.

           foo(<<HERE      # ok
           some text
           HERE
              );

       This style is a little unusual but some people like the whole here-document at the place its string
       result will expand.  If the code is all on one line (see "<<EOF" in perlop) then trailing comma
       considerations don't apply.  But both forms work and so are a matter of personal preference.

           foo(<<HERE);
           some text
           HERE

       Multiple values still require a final comma.  Multiple values suggests a list and full commas guards
       against forgetting to add a comma if extending or rearranging.

           foo(<<HERE,
           one
           HERE
               <<HERE      # bad
           two
           HERE
              );

   Disabling
       If you don't care about trailing commas like this you can as always disable from .perlcriticrc in the
       usual way (see "CONFIGURATION" in Perl::Critic),

           [-CodeLayout::RequireTrailingCommaAtNewline]

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

   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.

HOME PAGE

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

COPYRIGHT

       Copyright 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2019, 2021 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>.

perl v5.32.1                                Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline(3pm)