Best Practices for PowerShell Scripting (Part 5)

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

Throughout this article series, I have been talking about various best practices for PowerShell scripting. In the previous article, I began talking about some recommended best practices for creating PowerShell functions. As I explained at the beginning of that article, everybody seems to have their own ideas about what constitutes good practices for PowerShell function creation. The recommendations that I am making in this article series are based on techniques that have worked for me. These are the same techniques that I use when I create PowerShell scripts of my own. So with that said, I want to continue the discussion by talking about some more best practices for creating functions within your PowerShell scripts.

One of the first best practices that I want to mention is something that I probably should have talked about in the previous article. That best practice is that before you ever write the first line of code for a PowerShell function, you need to stop and think about who that function is for and how it will be used. I realize that this is kind of a no-brainer, but there is a method to the madness. Let me explain.

Since this article series is all about PowerShell scripting, let’s assume for a moment that the functions that you are creating are going to be local to the script that you are building and are not going to be reused by other scripts. That assumption simplifies things a little bit, but we still need to consider who is going to see the code and what your model for the script is going to be.

If for example, there is absolutely zero chance that anyone other than you will ever see the code then do whatever you want. It doesn’t really matter if you adhere to established best practices or not, so long as the code makes sense to you. If on the other hand, the code will eventually be seen by other developers or by Internet users who want to use your code as a reference then you need to take that into consideration. You should structure and document your code based on the intended audience. Let me give you an example.

Let’s suppose for a moment that I was writing a block of code that will never be seen by anyone else. In all honesty, I would probably comment the code so that if I came back to the code 6 months from now I could figure out what it was doing without having to go through and do a line by line review of the code. However, the comments would probably be somewhat sparse and they might not necessarily make sense to anyone other than myself.

On the other hand, if I were writing a block of code that might potentially be used by other Windows administrators, I would probably still keep the comments somewhat sparse but I would make sure that the comments that do exist in the code are meaningful and helpful to those who might be reviewing the code for the first time. This means documenting functions, variables, and anything else in the code that might be particularly tricky.

Of course sometimes it isn’t just seasoned IT professionals who end up accessing my PowerShell code. Much of the code that I write goes on to the Internet for educational purposes. Typically that code exists within the body of an article, and such an article would obviously explain how the code works. On occasion however, I have made PowerShell scripts available for download. When I create such a script, my rule of thumb for myself is that I document the script as if I were trying to explain it to my mother (who has probably never even heard of PowerShell). The point is that I do as much handholding as I possibly can without making the script so comment heavy that the actual code gets lost in a sea of comments.

Another consideration for writing PowerShell scripts is what you want your functions to do. In the previous article, I mentioned a few different best practices for PowerShell functions. I think I said that a PowerShell function should do one thing, and do it well. I also mentioned that code that will be used multiple times should generally be turned into a function. However, you still have to consider the structure of the script that you are writing. What do you really want the functions to do? Let me explain what I mean.

Some people write functions that perform major tasks. Such a function might for example, generate a report or perform health checks against dozens of servers. Other people write functions that are extremely granular. For example, I have seen people write a function that does nothing except for null a variable or check the operating system version. Still other people write functions that perform tasks that are more complex than a single operation, but that aren’t quite so monolithic as a report generator. Such a function might for instance, perform a complex database query or perform some sort of multistep calculation.

There is nothing wrong with any of these types of functions (although there are people who bitterly disagree with me on this point). In my mind, the important thing is to adopt a function creation philosophy for your script and stick to it. If you want to create functions that perform huge, monolithic tasks there is nothing wrong with that. Just don’t include super granular functions in the same script. Otherwise, your code can very quickly become confusing. This isn’t to say that you have to pick one particular coding style and use it forever. Just try not to mix coding styles within a single script.

Another best practice for PowerShell functions is something that I have only recently begun doing myself, but I think it makes a lot of sense. I like to include version numbers in my PowerShell functions.

A lot of people place a version number in the comment section of the PowerShell scripts that they write. That way they can track revisions to the script. I think that the same basic principle applies really well however, to PowerShell functions. If you think about it, a function is kind of like a miniature script. As a matter of fact, when you get into advanced PowerShell scripting it is even possible to create functions that exist outside of a script.

Taking the time to place version numbers within your functions serves two purposes. First of all, it can make a PowerShell script a little bit easier to debug. Suppose for instance that a particular feature within a script worked well in version 1.4, but it doesn’t work at all in version 1.8. In a situation like that, you would obviously want to know what has changed over the last few versions. By adding version numbers to individual PowerShell functions, you can tell at a glance which functions have been revised and which have been left alone.

The other reason for versioning your functions is that as I mentioned a moment ago, a function can exist independently of a script. Adopting good practices now will make it a lot easier to eventually transition into creating independent functions.

Conclusion

In this article, I have explained that there are a number of best practices for creating PowerShell functions. In the next article in this series, I want to talk about some more best practices for PowerShell scripting.

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