Fun With PowerShell Code Formatting

Introduction

In this post, we’ll take a look at some of PowerShell’s rules around code formatting. Code formatting is how you can layout your code statements.

For all of the examples, we’ll display the code, then under it the result of our code. In this article I’ll be using PowerShell Core, 7.1.3, and VSCode. The examples should work in PowerShell 5.1 in the PowerShell IDE, although they’ve not been tested there.

To run a snippet of code highlight the lines you want to execute, then in VSCode press F8 or in the IDE F5. You can display the contents of an array variable (or any variable) by highlighting it and using F8/F5.

In either environment, you can run your entire script by pressing F5.

Code Formatting

Unlike some languages, such as Python, PowerShell is extremely flexible when it comes to how you format your code. There are, in fact, very few rules around it.

Let’s take this first example. When I’m developing a script I tend to do so in steps. I write short pieces at a time, then I use the method of highlighting those lines of code and running using F8/F5 (depending on if I’m in VSCode or the IDE).

Here’s one downside, if you don’t have any lines of code highlighted pressing F5 will run your entire script (in either VSCode or the IDE). I have to admit, even though I’ve been using VSCode for a few years now old habits die hard and I still press F5 sometimes.

To prevent my entire script from running I add the following line at the top of my scripts. Once it is complete can remove it or comment it out.

if ( 1 -eq 1 ) { exit }

Here, 1 will always equal 1, so it will run the code in the script block. This is the exit command, which will cause a script to exit, or in other words stop running.

The real point of this example though isn’t the exit command, but the formatting of the if statement. As you can see, since the script block was so short, I was able to put it all on a single line.

But I didn’t have to. I could have placed it on multiple lines.

if ( 1 -eq 1 )
  { exit }

In this example, I placed my single line script block on the next line. Whenever I have a short script block like this, I usually indent two spaces, just because I think it is more readable. But that’s my personal preference. I could have placed it all the way on the left.

if ( 1 -eq 1 )
{ exit }

I could also have spread it out over multiple lines, as I did in the previous section, even though the code (the exit statement) was still only a single line.

if ( 1 -eq 1 )
{
  exit
}

Many people have a preference for putting the opening squiggly brace at the end of the line with the if statement, and PowerShell supports that as well.

if ( 1 -eq 1 ) {
  exit
}

I tend to prefer the former method as it makes lining up your opening and closing squiggly braces much easier, but fortunately PowerShell supports what ever method you wish to use to format your code.

More Fun with Code Formatting

Next, I’d like I to mention two small things that fall into the code formatting realm.

First, it is possible to compact multiple lines of code into a single line in PowerShell. All you have to do is use a semicolon ; to separate each one.

$a = 'Hi'; $b = 'Mom'; "$a $b"

Result:
Hi Mom

The second thing I’ll mention is comments. Comments begin with a # (pound sign, or as some call it a hash tag).

# This is a comment

Comments can go after a section of code.

$var = 2   # Assign 2 to the variable $var

PowerShell also supports multi-line comments. You start and end them with <# and #>.

<#
   This is a multi line comment.
   You can also put blank lines in here.

   See, easy.
#>

The opening and closing <# #> don’t have to be at the beginning of the line.

<#--------------------------------------------
  You don't have to indent either.
--------------------------------------------#>

Documenting Your Code Formatting Standards

If you work in an organization, even one with just two of you doing PowerShell development, it’s incredibly important to document your coding standards. This will ensure the code produced by all developers in your organization has a consistent look and feel.

So what types of things should go into the document? Well how about something as simple as indenting your code. When you indent, for example as part of an if statement, should it be two spaces? Four? More?

And should it be spaces, or should you use the TAB character? Personally I hate the TAB character, leads to formatting issues when going between platforms. Remember, PowerShell runs on Windows, macOS and Linux. But as I like to say “hey you do you”.

How about the opening squiggly brace of a script block. Should that be at the end of (for example) your if statement, or should it go on the next line?

How about comments? Let’s say you decide each script (PS1 file) should have a header. What should go in it? A copyright notice? The author name? A description of the script? What order should it be in?

There is one rule that is almost universally accepted, never use the short version of names for cmdlets, always spell them out. For example, gci is short for Get-ChildItem. When you are in the terminal just looking around, it’s perfectly valid to use gci, but in a script always spell out the full Get-ChildItem cmdlet name.

These are just a few ideas to get the ball rolling. You should keep your standards document as brief as possible, but cover as many things as necessary to create a consistent look and feel when coding new PowerShell scripts.

There are hundreds of good books and blog sites that discuss and have examples of coding standards. In the end go with what works best for you, but the important part, stick with it!

Make it a group decision as much as possible. Your entire coding team should have input into the standards. Even more important, when a new member comes into the team before they write the first line of code they should be introduced to your coding standards.

I would also avoid using something like a Word document to store the standards. Instead, put them online in a place that is easy to search and index. If your team has it’s own internal Wiki, that’s a great place. Or, author them in Markdown format and store them in a GitHub repository.

Wherever you put them, accessibility is key. Standards should be easy to reference, and to find the item you need.

Conclusion

This post covered the flexibility of code formatting in PowerShell, as well as touched on a few items such as commenting. More importantly, it touched on the importance of documenting and standardizing your code formatting rules.

With this info I hope you jump right on creating your own set of coding standards!

The demos in this course came from my Pluralsight course PowerShell 7 Quick Start for Developers on Linux, macOS and Windows, one of many PowerShell courses I have on Pluralsight. All of my courses are linked on my About Me page.

If you don’t have a Pluralsight subscription, just go to my list of courses on Pluralsight. At the top is a Try For Free button you can use to get a free 10 day subscription to Pluralsight, with which you can watch my courses, or any other course on the site.