Best Practices for PowerShell Scripting (Part 4)

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

Welcome back. Throughout this article series, I have talked about a huge variety of best practices for PowerShell scripting. So far however, there is one particular subject that I haven’t really touched on all that much – Functions. There are a huge number of best practices with regard to PowerShell functions and I want to take the opportunity to share some of those best practices with you.

Before I start talking about the actual best practices, there is a bit of a disclaimer that I need to get out of the way up front. When it comes to writing PowerShell functions, it seems that almost everybody has their own idea of how to do a best. If you were to do a web search on best practices for writing PowerShell functions, you would probably find a number of contradictory best practices. I personally take this to mean that PowerShell functions can be constructed in a variety of ways and for a variety of purposes, and that you should really do what makes the most sense for the task at hand.

My approach to talking about PowerShell functions is to give you the best practices that work for me. These are all practices that I use on a day-to-day basis when I write PowerShell code. My best practices are not necessarily the same as what you might get from someone else. So with that said, let’s get started.

My first best practice for creating PowerShell functions is to use functions in an appropriate manner. I have heard some people say that every PowerShell function should accept one input parameter and should return one value. For the life of me, I cannot understand the logic behind that particular best practice. Don’t get me wrong, there is nothing wrong with creating a PowerShell function that accepts an input parameter and returns a value. It’s just that if you rigidly adhere to only creating these types of functions, then you really limit yourself.

In my opinion, PowerShell function should be used anytime that you need to write repeatable code. If there is a certain task that is going to have to be performed more than once within your script, then that task is probably going to be a good candidate for inclusion in a function. There are those who disagree with me, but when well-written, functions can actually make your code easier to follow. Let me explain.

In one of the earlier articles in this series, I talked a little bit about the importance of using good variable names so that anyone who reads your code will be able to understand the logic behind the code. The same basic concept applies to functions, but naming conventions may be even more important than they are for variables (if that’s even possible).

One of the best practices that has come about in the last couple of years is to name PowerShell functions in a manner that is similar to that of native PowerShell cmdlets. Suppose for a moment that you are developing a PowerShell function to display a particular report. You could create a function called Report, but that would be a little bit ambiguous. I mean what does the Report function do? Does it create a report? Does it E-mail a report? On the other hand, if you create a function named Display-Report then there is little doubt as to what that particular function does.

This brings up another point. I mentioned that function should be used anytime that you have repeatable code. There is actually one more really good use case for functions. Functions can also be helpful if you need to segment a really long PowerShell script.

Suppose for a moment that you’ve got an exceptionally long PowerShell script that does a lot of different things. In this type of situation, you could create a series of functions that handle major tasks within the script. The idea behind this concept is simple. It reduces your main code body to the absolute minimum, and makes it easy to follow. This is especially true if you use PowerShell cmdlet style names for your functions. When all is said and done, the main body of a complex script could appear as a sequence of simple cmdlets. For example, a long and complex script that builds some kind of report might have its code body reduced to this:

Gather-ReportData

Compile-Report

Display-Report

Share-Report

As you can imagine, having a few lines like the ones shown above can make the script’s logic a lot easier to follow than if the main body contained thousands of lines of code.

Of course all of the code has to go somewhere. So how can you construct the functions themselves in a way that maintains the readability of the script?

My advice is to include a comment section at the top of the script. This comment section should list the name of each function, as well as what the function does.

If you have been following along throughout this entire series, then this particular statement might seem like a bit of a contradiction. In one of the earlier articles I mentioned that comments are important, but that going overboard with the comments can actually make your code less readable. So why am I now encouraging a detailed function description at the top of the script?

The reasoning behind this recommendation goes back to naming conventions. Remember that I said that it has become commonplace to name PowerShell functions in a way that resembles the verb-noun naming convention of PowerShell cmdlets. Suppose that you decide to name all of your functions in this way, and that later on someone who doesn’t know PowerShell all that well attempts to read your code. Such a person might have trouble distinguishing between obscure PowerShell cmdlets and your function names. Listing all of the functions at the beginning of the script removes any doubt as to the naming conventions that are used in the script.

While I am on the subject of comments, it is also a good idea to include some comments at the beginning of each function. You might for instance repeat the function’s purpose if it is not made obvious by the function name. Likewise, if your function accepts any input or if it returns any values then that should be documented within a comment at the beginning of the function.

Conclusion

When it comes to writing PowerShell functions, there isn’t a lot of consistency with regard to the established best practices. Everyone it seems, has their own way of doing things. Regardless of whether you choose to adopt some or all of my best practices, or you choose to do things your own way, your goal should be to make your code as easy to read as possible.

In the next article in this series, I am going to spend some more time talking about PowerShell functions. I have really only just begun to scratch the surface with regard to functions and there are more best practices that I want to share.

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