Perl::...Newline(3pm)

📦
version 100 · 7 versions
, in ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline — bestie, this one's all about putting a comma at the end of a list at newline. That's it, that's the whole moment. 💅

(also, hi, this is a section 3pm page from the User Contributed Perl Documentation — iykyk 🫶)

✨ DESCRIPTION ✨

Okay so this policy is part of the Perl::Critic::Pulp add-on. What it does is it asks you (politely, it's not mean) to drop a comma at the end of a list (or whatever) when that list ends with a newline. Like:

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

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

And before you panic — this makes literally zero difference to how the code runs. None. So the policy is low severity and lives under the cosmetic theme (peep "POLICY THEMES" in Perl::Critic if you want the lore).

The whole idea, the vibes behind it, is that editing code is just easier this way — you don't have to remember to go back and add a comma to the item above when you're extending or rearranging lines. No mental gymnastics, no forgotten commas, no crying. 😌

Now, if the closing bracket is chilling on the same line as the last element? Then no comma is required, bestie. You can have one if you want, but nobody's demanding it:

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

Parens around an expression are not a list, so nothing is demanded here, for instance:

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

BUT — and this is the plot twist — a single-element paren expression is a list when it shows up in an array assignment or a function/method call. So:

    @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. Slay:

    return ($x
            + $y    # ok
            );

Whether code like that is a single-value expression or a list of only one value depends on how the function is specified. And honestly? There's nothing in the text (nor even at runtime) that would say for sure. It's giving mystery. 💀

It's handy to include parens around a single-value expression to make it clear that some big arithmetic is all part of the return — especially if you can't remember precedence levels (me neither bestie 🙈). In such an expression, a newline before the final ) can help keep a comment together with a term for a cut and paste, or keep you from losing a paren if you comment out 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 having 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, periodt:

    foo(<<HERE);
    some text
    HERE

Multiple values still require a final comma, though. Multiple values suggests a list, and full commas guard against forgetting to add a comma when you're 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 it 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 here is that if foo() takes only two arguments, then you don't want to write a trailing comma, because it might suggest something more could be added. Makes sense tbh.

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. Different strokes for different folks, bestie. 🧚

🏠 HOME PAGE 🏠

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

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>.

fr fr, that's the whole page 💖 generated on 2025-10-21, sitting pretty at perl v5.40.1, from the User Contributed Perl Documentation. go forth and comma responsibly, bestie, ily 🫶💅✨
📦 where this page comes from