Splatting vs. backticks

[nightroman]

The preferred way to wrap long lines is to use splatting (see
About_Splatting) and PowerShell's implied line continuation inside
parentheses, brackets, and braces -- these should always be used in
preference to the backtick for line continuation when applicable.

I slightly disagree with splatting, especially with the word "preferred". It is
a possible way, not preferred.

Splatting avoids backticks, this is probably a good thing. But it introduces
some drawbacks, too. It would be nice if the guideline mentions them, so that
people understand the consequences and make their choice being well informed.

The main drawback is absence of code completion of parameters and even some
parameter values on using the splatting approach. In contrast, TabExpansion
works fine across multiple lines with backticks. TabExpansion is a real time
saver.

Another drawback is necessity to introduce a variable because unfortunately
splatting requires a variable. It is not a big deal but it is just not natural.

Yet another minor thing is understanding the code. When a statement starts with a
command name then it's clear what it is even if it has lengthy continuation
with backticks. In contrast, if a statement starts with a lengthy hashtable
assigned to a variable then without looking at the command after it it is
less clear why is this needed.

[Jaykul]

The Style Guide does not care if you're using notepad or Sublime, ISE or Visual Studio.

In an ideal world, switching from a 600-character command line to a splatted hashtable (and back) should be as simple as right-clicking the line and picking "reformat as splatted hashtable" -- I suggest you file a feature request for ISE asking for that.

Having said that: your tool's lack of "code completion" or "TabExpansion" is not a concern for the style guide. We just want it the code to look good when it's done. We can't let editor features dictate what good code looks like -- it's counter-productive. What I mean is: I don't think lack of TabExpansion is a valid argument in support of a particular style.

Write it as one long line so your tool will help you, and then reformat it.

Your other points are more valid ;-)

[Jaykul]

I don't think introducing a variable is a problem -- in fact, I think there are plenty of other cases where you will have to introduce variables to make the code readable. For instance: when you need to call a command to get the value to pass to a parameter, it's probably good style to introduce a variable rather than nesting the call in a subexpression. This is much more significant than the splatting case, because you would introduce many variables, and can probably be avoided by using splatting 😉

I do think a command invocation is much easier to read when it starts with the command and then the parameters. I would even suggest that if you're splatting, it's good form to use the command name as (part of) your splatting variable name, to help with that.

One issue is that backtick line-continuation is a code smell -- it not only makes it hard to read things, but it also makes things harder to edit (because you have to remember to keep fixing the backticks as you go). You can lessen that impact by writing EXACTLY one parameter per line (and never wrapping in the middle of one parameter), but it's still harder to read and edit code written that way.

Another issue is that backticks don't help in the case where you need to pass the output of one command as a parameter to another -- you end up assigning a variable anyway.

Perhaps a simple example I had to write today will help. I need to edit the content of a file, but the name of the file had to be determined by calling a function: Get-Version and then joining that with the current path, and the module name (from a variable):

$Version = Get-Version -Project $ModuleName
$ReleasePath = Join-Path $Pwd $Version
$FilePath = Join-Path $ReleasePath "${ModuleName}.psd1"
$ManifestContent = Get-Content -Path $FilePath
$ManifestContent = $ManifestContent -Replace "ModuleVersion = '[\d\.]+'", "ModuleVersion = '$Version'"
Set-Content -Path $FilePath -Value $ManifestContent

I could have saved some lines (and a lot of variables) by doing some of the work in the same line:

$FilePath = Join-Path $(Join-Path $Pwd $Version) "${ModuleName}.psd1"
Set-Content -Path $FilePath ((Get-Content $FilePath) -Replace "ModuleVersion = '[\d\.]+'", "ModuleVersion = '$Version'")

Of course, that makes my lines too long, so I could wrap them:

$FilePath = Join-Path $(Join-Path $Pwd $Version) "${ModuleName}.psd1"
Set-Content -Path $FilePath ((Get-Content $FilePath) `
            -Replace "ModuleVersion = '[\d\.]+'", "ModuleVersion = '$Version'")

But wait, that's deceptive. If we're going to allow line wrapping at all, we must require that you wrap only on each parameter:

$FilePath = Join-Path $(Join-Path $Pwd $Version) "${ModuleName}.psd1"
Set-Content -Path $FilePath `
            -Value ((Get-Content $FilePath) -Replace "ModuleVersion = '[\d\.]+'", "ModuleVersion = '$Version'")

The problem is, that's still too long.
I could try splatting them:

$FilePath = Join-Path $(Join-Path $Pwd $Version) "${ModuleName}.psd1"
$SetContent = @{
    Path = $FilePath
    Value = (Get-Content $FilePath) -Replace "ModuleVersion = ['\d\.]+", "ModuleVersion = '$Version'"
}
Set-Content @SetContent

From my point of view, the second one has a few advantages:

• I can line up my parameters without indenting to the length of the command name, so my code is no longer too long for GitHub 😜
• The nested command call is now clean (if -Replace was a parameter to Get-Content, I would have no issues with this formatting).
• There are less temporary variables created than the first (very clean) way I showed.

I would argue that the very first code sample is noticeably easier to read and follow, and is the best practice (rather than nesting commands). I don't actually write my code like that, usually, but in the back of my mind I feel it's better. In the real project, this code was written without line wrapping at all, and my lines are around 150 characters long (and I am ok with that length, and nobody has complained about it).

[Jaykul]

So -- given all of that, if my project/team had a strict limit on line length, and the reason my command is too long is purely because of the number of parameters, then we must solve it one way or the other.

The question is (basically, we just need to take a vote here): in the scenario where the command line is just too long, and you have to wrap the line -- do you truly recommend backticks over splatting?

[KirkMunro]

Just to add to the mix, here's an example of how I use backticks quite often:

Get-Service `
    | ForEach-Object {<# Do some stuff #>} `
    | Stop-Service -WhatIf -PassThru `
    | Format-List -Property *

Style-wise, with the vertically aligned pipe symbols, this makes for very readable one-liners. Many others argue against the backtick, and placing the pipe at the end instead, but that doesn't give me the same readability benefits. If I did happen to forget a backtick this way, PowerShell would give me an error because I'd have an empty pipe element, so that's not an issue. So in this case, where the command line is too long and I have to wrap the line, I truly recommend backticks over pipe symbols at the end of the line.

[Jaykul]

I actually like the looks of that, except for the part where I still really dislike backticks! 😈 and they're really easy to screw up (because even an invisible space after them breaks them). I mean, I get that you mostly avoid that because they crash if you actually run the code, but it's still a break you can't spot in a code review.

[KirkMunro]

1. In general I dislike them as well. For the syntax example I'm
   providing, I think PowerShell should be able to support that without
   backticks, especially since you can't lead in with a pipe. It isn't on
   Jason's priority list though.
2. Spaces don't have to be invisible. I have an ISE add-in for example
   that shows whitespace. I imagine other editors have similar features.
3. There is an issue logged on PSScriptAnalyzer to check for backticks with
   nothing but whitespace at the end of the line, among other things. I don't
   think the risk of the invisible space warrants recommending against
   backticks.

[Jaykul]

Need to call a vote on backticks. I don't like things (like here-strings) that make white space significant in a language where it normally isn't. With here-strings, I feel the added value is significant for a few scenarios, but with backticks I never have.

[KirkMunro]

My vote: allow backticks, with comments in the style guide clearly indicating that you should limit your use of backticks as a line continuance character to scenarios that improve code readability (when lines of script would otherwise be too long), and when doing so you should follow one of two models:

a) a single backtick to spread one command across two lines, in which case the second line should be indented and the backtick should be in between parameters or pipeline elements;

e.g.

Get-Something -Name ThisIsALongName -Type WhatColorIsYourParachute -SomeSwitch `
    -SomeOtherParam AndItsValue -PassThru

b) multiple backticks to spread one command across more than two lines, in which case each line should be indented and each line should contain its own parameter or pipeline element

e.g.

Get-Something `
    -Name ThisIsALongName `
    -Type WhatColorIsYourParachute `
    -SomeSwitch `
    -SomeOtherParam AndItsValue `
    -PassThru

or

Get-Something -Name ThisThing `
    | Where-Object {$_.Description -match 'Special'} `
    | ForEach-Object {$_.SomeMethod()} `
    | Sort-Object -Descending

In the second scenario, when considering the former example (spreading parameters across multiple lines), splatting is generally the preferred style, however backticks may be used.

[jrich523]

no backtick!

[dlwyatt]

Honestly, I'm starting to prefer backticks over splatting. I drank the Kool-Aid for a while too, but I prefer to see the command that I'm calling first, then the parameters. Like Kirk's first example, except I usually do it like this:

Get-Something -Name           ThisIsALongName `
              -Type           WhatColorIsYourParachute `
              -SomeSwitch `
              -SomeOtherParam AndItsValue `
              -PassThru

I'm still on the fence about whether to align the arguments to the parameters, as I've done here, or just align the parameter names. Either way, I find this much easier to read at a glance than splatting, which gives me a bunch of code to set up a hashtable (which doesn't always look intuitive), then sneaks in one quick little Get-Something @params call that I can easily overlook.

[PowerSchill]

I agree with jrich523. Backticks should not be used.

[dlwyatt]

My only argument against backticks was that if you accidentally include whitespace after it, it stops functioning as a line continuation character. However, these days, we're putting code analysis tools in place that complain if you have trailing whitespace anyway, which makes this less of a problem.

[mwjcomputing]

I am not in favor of backticks. I am saying no, but recognize Kirk’s points as valid. If you want a vote though, no.

[darkoperator]

My vote no backticks

On May 29, 2015, at 12:29 PM, Matt Johnson notifications@github.com wrote:

I am not in favor of backticks. I am saying no, but recognize Kirk’s points as valid. If you want a vote though, no.

On May 29, 2015, at 11:04 AM, Kirk Munro <notifications@github.commailto:notifications@github.com> wrote:

My vote: allow backticks, with comments in the style guide clearly indicating that you should limit your use of backticks as a line continuance character to scenarios that improve code readability (when lines of script would otherwise be too long), and when doing so you should follow one of two models:

a) a single backtick to spread one command across two lines, in which case the second line should be indented and the backtick should be in between parameters or pipeline elements;

e.g.

Get-Something -Name ThisIsALongName -Type WhatColorIsYourParachute -SomeSwitch `
-SomeOtherParam AndItsValue -PassThru

b) multiple backticks to spread one command across more than two lines, in which case each line should be indented and each line should contain its own parameter or pipeline element

e.g.

Get-Something -Name ThisIsALongName
-Type WhatColorIsYourParachute -SomeSwitch
-SomeOtherParam AndItsValue `
-PassThru

or

Get-Something -Name ThisThing | Where-Object {$_.Description -match 'Special'}
| ForEach-Object {$_.SomeMethod()} `
| Sort-Object -Descending

In the second scenario, when considering the former example (spreading parameters across multiple lines), splatting is generally the preferred style, however backticks may be used.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/15#issuecomment-106840493.

—
Reply to this email directly or view it on GitHub #15 (comment).

[Jaykul]

I say if you want the name there, put it the variable name, and if you want to line them up, do that too ;-)

$GetSomethingParam = @{
    Name         = "ThisIsALongName"
    Type         = "WhatColorIsYourParachute"
    SomeSwitch   = $true
    AnotherParam = "AndItsValue"
    PassThru     = $true
}
Get-Something @GetSomethingParam

I think based on this poll, that people who like backticks are in the minority, not to mention the comments on PowerShell.org when they polled on this for the book.

I also don't buy the argument that it's not really a big deal that whitespace screws up line continuation (especially when you're adding extra whitespace and trying to line things up). I don't think it's worth confusing the matter by discussing all these options in the guide -- and that's already the call that Don et. al. made in the first version of the Practices book.

Which reminds me, this rule is in the style guide and the best practices book -- is everyone OK if I pull it from the best practices and leave it just in the style guide?