Best practices for creating and writing PowerShell functions

Despite the relative ease with which you can add functions to your PowerShell scripts, creating functions is something of an art form. As someone who works in PowerShell constantly, I have come up with several best practices for PowerShell functions, and I wanted to take the opportunity to share those best practices with you.

creating PowerShell functions
Shutterstock

The name matters when creating PowerShell functions

The first best practice that I wanted to mention is that the function’s name matters. In theory, you could name a function anything that you want so long as you are not duplicating a function name or using one of the words that PowerShell has reserved for itself. Even so, there are at least two reasons why it is a good idea to put some thought into the name of your function.

The first of these reasons is that functions can be reused. There have been several occasions in which I created a function for use in a specific script but then later borrowed that function for use in another script. In some cases, I have pasted the function directly into the script, but in other situations, I made the function a part of a module.

If you’re not familiar with modules, they are the mechanism that makes PowerShell extensible. You’ve probably noticed how Microsoft server applications include application-specific PowerShell cmdlets. For example, there are a number of PowerShell cmdlets related to System Center Virtual Machine Manager. These application-specific cmdlets are added through the use of modules.

Believe it or not, Microsoft makes it relatively easy to build your own modules, thereby making it possible to create custom PowerShell cmdlets. I don’t want to rehash the technique here because I have covered it in a separate article. For right now, though, the important thing to know is that the custom cmdlets associated with modules are really just functions.

The takeaway is that you never really know when a seemingly mundane function that you write will become useful enough to warrant its inclusion in a PowerShell module. That being the case, I make it a point to try to name my functions to mimic the structure of native PowerShell cmdlets. The cmdlets that are built into PowerShell are based on verb-noun combinations (Do-Something). I use a similar naming convention for my functions just in case they ever end up being turned into cmdlets.

Write self-documenting code

powershell parameters
Shutterstock

I mentioned earlier that there are two main reasons why the names that you pick for your PowerShell functions matter. The second reason why the naming convention matters is that you should always try to write self-documenting code.

Don’t get me wrong. I have nothing against adding comments to PowerShell code. In fact, I would view comments as an essential part of any long or complex PowerShell script. Having said that, though, there is such a thing as too having too much of a good thing. On occasion, I have downloaded scripts that were so comment-heavy that it became difficult to locate the actual code among all of the comments. On at least one occasion, I actually found myself deleting some of the comments just so that I could make better sense of the code.

Obviously, that’s an extreme example, but there is a point to all of this. One of the best ways to help anyone who might be reading your script later on is to write what I call self-documenting code. This essentially means doing three main things.

First, it means making sure that you use variable names that reflect the variable’s purpose. Sure, we’ve probably all written really short scripts that use variables with names such as $A, and there is really nothing wrong with that. However, if you’re writing something longer or more complex, you can do yourself and others a favor by using meaningful variable names.

The second part of writing self-documenting code is to write PowerShell cmdlets in long-form rather than using abbreviations or aliases. This means using Format-Table instead of FT, or Select-Object instead of Select. This helps to take the ambiguity out of the code for those who are less experienced in PowerShell.

The third part of writing self-documenting code is to use comments where appropriate. Ideally, your function names and variable names should do a good job of spelling out what the function is doing. Still, it never hurts to add a comment detailing a function’s purpose or what a particularly tricky block of code does.

Do one thing and do it well

creating PowerShell functions

Another best practice that I have picked up over the years is that when it comes to creating PowerShell functions, it’s a good idea to create functions that do one thing and do it well. On occasion, I have admittedly written functions that were way overcomplicated and more like standalone scripts. These days though, I try to stay away from the monolithic functions and try to create smaller functions that do one very specific thing.

There are two reasons why I recommend using a lot of simple functions, as opposed to a couple of big ones. First, simple functions are easier to troubleshoot. If you have a problem, it will be a lot easier to figure out what’s going on if you avoid unnecessary complexity in your functions. Second, creating a lot of smaller functions instead of a couple of large ones can help make the code easier to read, especially if you use meaningful names for those functions.

When creating PowerShell functions, keep it simple

As you probably noticed, most of my best practices focus on keeping functions simple and writing them in a way that makes them easy to understand. One last thing that I want to be sure to mention, though, is that it’s helpful to try to avoid using one function to call another if at all possible.

Unfortunately, if you’re doing something really complex, calling a function from within a function might be unavoidable. However, troubleshooting will be a lot simpler if your functions are self-contained and do not depend on external dependencies such as other functions.

Featured image: Shutterstock

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