Best Practices for PowerShell Scripting (Part 3)

If you would like to read the other parts in this article series please go to:

In my previous article in this series, I talked about the importance of using meaningful variable names. Using good, meaningful variable names goes right along with the concept that I introduced in the first article of writing self documenting scripts. So does declaring your variables at the beginning of the script and using comments to explicitly spell out what each variable is used for. Even so, there is a lot more to building a self documenting script than just adhering to best practices for variable usage. There are plenty of other things that you can (and should) be doing to make your scripts easier to read.

The first such best practice is actually a major pet peeve for me. In most cases, you should avoid using aliases in PowerShell scripts. In case you aren’t familiar with PowerShell aliases, I am referring to the ability to shorten commands or parameters into something almost unrecognizable. I will give you some examples of what I am talking about in a few minutes, but first, pay attention to the way that I worded this particular best practice. My wording wasn’t an accident. I said that in most cases you should avoid using aliases in PowerShell scripts.

There are two things worth paying attention to in this statement. First, I used the words most cases. There is at least one big exception to the rule in which I think that it is perfectly OK to use an alias in a script. There are also a few aliases that ideally shouldn’t be used in a script, but I think most people will recognize. The other part of the way that I worded this particular best practice that I want to point out is that I said that you should avoid using aliases in PowerShell scripts. It’s OK to use aliases when you are manually entering commands into PowerShell. However, scripts tend to be longer and more complex. Since there is a chance that someone else may eventually need to decipher what you wrote, it is a courtesy to avoid using aliases within the scripts that you write.

OK, so I promised to give you some examples of PowerShell aliases. Some of the aliases that you might occasionally encounter include IPMO, GWMI. Do you know what these commands do? If not, then you probably get my point. Aliases can make PowerShell code difficult to read. The IPMO alias is an abbreviation for the Import-Module cmdlet. Similarly, the GWMI alias is short for Get-WMIObject. The point is that your code will be a lot easier for other people to figure out if you avoid using aliases.

I mentioned that there was a big exception to the rule. In some versions of PowerShell, Where-Object can be shortened to Where. In my opinion, Where is easier to read than Where-Object, especially since Where is extensively used in some other programming languages. Incidentally, the Where-Object cmdlet can also be replaced by a question mark. However, I recommend not doing so because unless someone knows that a question mark means Where-Object, they will be left trying to figure out exactly what the code does.

So what about those grey areas that I mentioned? Well, I have to admit that I am a little bit on the fence when it comes to certain aliases. There are a handful of aliases that are so commonly used that most people who have a basic understanding of PowerShell probably recognize them. Even so, those particular aliases are not exactly intuitive and could be a bit cryptic to those who do not have experience with PowerShell. I’m talking about aliases such as FT (Format-Table) and FL (Format-List). In my opinion, it’s probably best to go ahead and spell out the full cmdlets, but it probably isn’t going to cause any major problems if you choose not to.

While I am on the subject of self documenting scripts, I want to take a moment and talk about the importance of script appearance. At first this probably sounds ludicrous. Unlike a Microsoft Word document, you aren’t going to be specifying fonts and adding pictures to make your PowerShell scripts look pretty. Even so, there are some things that you can do to give your PowerShell scripts a nice appearance, thereby making the scripts easier to read.

As you probably know, PowerShell doesn’t really care about line spacing, capitalization, or indention. Even so, using such elements in an appropriate manner can make your script easier to use.

When I write a PowerShell script, I like to insert a few blank lines between major functional areas of the script. Yes, I use blank lines to separate functions from one another and from the script’s body, but I sometimes also use blank lines within a script’s body.

If you think back to the previous article, you will recall that I suggested declaring all of your variables at the beginning of the script. You could add a few blank lines after the last variable declaration as a way of creating a visual break between the variable section and the script body.

Even though I do not personally use this method, I know some people who organize PowerShell scripts into three sections – variable declarations, calculations, and output. If you like to use this particular approach to organizing your scripts, then a few blank lines between sections can help make it a little easier to tell where one section ends and the next begins.

Your use of capitalization can also make a script easier to read. Microsoft generally recommends that when entering a PowerShell cmdlet (or a parameter), you capitalize the first letter of each word. For example, you might type ForEach-Object rather than foreach-object. Inserting capital letters at the beginning of each word makes it easier to read the verbs and nouns that make up a cmdlet. This isn’t really a big deal for short cmdlets, but some cmdlets make use of multiple words.

There is one area where I tend to go against Microsoft best practices. I like to capitalize acronyms within PowerShell cmdlets, because I think that doing so makes the cmdlet easier to read. For example, I might use Get-WMIObject instead of Get-WmiObject. This one is just a personal preference and it is OK to either capitalize the entire acronym or to capitalize only the first letter.

Finally, if you choose to indent blocks of code then be sure to use indention in a consistent manner throughout the script. Otherwise the script may end up being confusing to read.

Conclusion

In this article, I have outlined a number of different best practices for writing PowerShell scripts. What all of these best practices really boil down to is making the code easier to read. Of course there is one big part of the code that I haven’t really touched on yet – functions. There are a huge number of best practices that apply to writing PowerShell functions. I will start discussing function related best practices in the next article.

If you would like to read the other parts in this article series please go to:

Leave a Comment

Your email address will not be published.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Scroll to Top