Posey's Tips & Tricks
Stop Doing these 5 PowerShell Function Practices!
Here's a look at five common PowerShell function mistakes that can make scripts harder to read, troubleshoot and reuse.
In the world of IT, we tend to talk a lot about best practices. But what about worst practices? For this post, I thought it might be fun to take a look at some worst practices for building functions in PowerShell scripts. As I do, keep in mind that this list is based solely on my own observations as someone who spends a lot of time writing PowerShell code. So let's get started.
1. Building Functions Just Because
The number one worst practice that I have run into in the real world is that of creating functions "just because." Functions primarily exist as a tool for avoiding the need for writing the same code over and over again within a script. Rather than doing that, you can just write the code once, turn it into a function and then call the function as many times as you need to.
On the other hand, I have seen scripts where the author has broken the script down into three to five line chunks and turned every chunk into a function, even if there is no repeated use of the code. In one such case, I saw someone use this approach because a teacher had once told them that all code belongs in functions.
2. Over Engineering a Tiny Script
Along the same lines, another worst practice is that of over engineering a tiny script. The idea is that someone builds a simple admin script that only consists of about a dozen lines of code. However, they then try to apply all of the PowerShell best practices that we so often hear about and suddenly that 12 line script contains over 300 lines of code.
Don't get me wrong. There is nothing wrong with writing bullet proof code that adheres to all of the established best practices. At the same time though, not every PowerShell script has to be written with production grade code. Sometimes, there is nothing wrong with creating a quick and dirty script, especially if nobody other than you is ever going to use it.
The problem with over engineering a tiny PowerShell script (aside from the time that it takes to build and debug the script) is that the script's complexity often leads to the script becoming far more difficult to read and more difficult to modify. You can no longer just glance at a few lines of code to see what the script does. Instead, modifications involve manually tracing hundreds of lines of code just to figure out how the script currently works.
3. Creating Massive Functions
While there are various philosophies regarding how and when functions should be created and what those functions should do, my basic approach has always been that a function should do exactly one thing, and do it well. A function might for example, perform a database query, validate user input, or send an email. Occasionally though, I have run into functions that consist of 500 lines of code and that perform 20 different tasks.
While there is technically no rule against this approach, I have found that if functions are kept small and designed to perform exactly one task, it makes the troubleshooting process a lot easier. If you run into a problem, you not only know which function is to blame, but you can also immediately narrow down the problem to just a few lines of code.
4. Returning Everything But the Kitchen Sink
In a way, this one ties into the worst practice of creating massive functions. It's very common to pass parameters to a function and return values. Occasionally however, I have seen functions that require a huge number of input parameters and that return just as many values. This approach not only leads to bloated functions, it also makes it difficult to reuse the function for other purposes.
My advice is to limit the number of parameters that you pass to and return from a function. A single parameter is ideal, but it isn't always realistic. If your function is performing a complex task and you just can't get around the need for passing lots of data to the function, consider adding that data to a custom object and then passing the object to the function instead of trying to handle a long list of individual variables.
5. Cleverness Over Clarity
This last one might be more of a pet peeve than an actual worst practice, but it involves functions that take lots of shortcuts and employ obscure coding techniques, presumably to impress someone. While this type of code can undoubtedly work, it's difficult to read the code and even more difficult to figure out how the function works and what it is actually doing. My advice is to always use simplicity over cleaver coding tricks.
About the Author
Brien Posey is a 22-time Microsoft MVP with decades of IT experience. As a freelance writer, Posey has written thousands of articles and contributed to several dozen books on a wide variety of IT topics. Prior to going freelance, Posey was a CIO for a national chain of hospitals and health care facilities. He has also served as a network administrator for some of the country's largest insurance companies and for the Department of Defense at Fort Knox. In addition to his continued work in IT, Posey has spent the last several years actively training as a commercial scientist-astronaut candidate in preparation to fly on a mission to study polar mesospheric clouds from space. You can follow his spaceflight training on his Web site.