If you would like to read the other parts in this article series please go to:
- Best Practices for PowerShell Scripting (Part 2)
- Best Practices for PowerShell Scripting (Part 3)
- Best Practices for PowerShell Scripting (Part 4)
- Best Practices for PowerShell Scripting (Part 5)
- Best Practices for PowerShell Scripting (Part 6)
Introduction
About ten years ago I made the decision to start a web-based business. At the time, none of the off the shelf web applications would do what I needed them to do, so I knew that I had no choice but to build the website from scratch. The project ended up being a lot more involved than I ever anticipated. In the end, I had written over 4000 pages of ASP code.
Needless to say, completing this project felt like quite an accomplishment. This was especially true given that I didn’t know anything about ASP before I started. Excited, I showed some of the code to a friend who was a professional ASP developer. He responded by telling me not to show the code to anyone else. He said that while my application was functional, it violated almost every established best practice for ASP programming. I felt deflated to say the least, but that hard lesson taught me that there is more to development than just writing code and that adherence to established best practices is important for a number of different reasons.
I don’t really write very much ASP code these days, but if you’ve read much of my stuff on this site then you know that I write a lot of PowerShell articles. Like ASP, there are a number of different best practices for building PowerShell scripts. What I have found is that these best practices don’t really matter very much if a script only consists of a few simple lines of code. For longer scripts however, adhering to certain best practices becomes essential.
Believe me when I say that there are some really long PowerShell scripts in existence. Over the weekend for example, I was working with a script that Microsoft created for converting Windows image files into virtual hard disks. This script (Covert-WindowsImage.ps1) contains 4434 lines of code, as shown in Figure A. It’s hard to imagine how difficult it would be to debug or to modify such a lengthy script without adhering to established best practices while developing the script.
Figure A: Some PowerShell scripts are really long.
So with that said, I want to spend some time talking about some of the best practices for PowerShell scripting. As I do, I will also try to explain why the various best practices are important.
Opening Comments
If you are going to be writing a PowerShell script that consists of more than just a few lines of code, then I highly recommend adding a header containing a few lines of text to the top of the script. It’s ultimately up to you what text you include in these comment lines, but I recommend including things like the name of the person who built the script, the script date, the script version, a description of what the script does, and some keywords.
With that said, I have to tell you that I have never been the type of person who enjoys formality. I am more the type of person who would rather just get the script written than to start out by including a formal header at the top of the script. Even so, script headers do have their place even for non-developers. Let me explain.
Suppose for a moment that you wrote a fairly elaborate PowerShell script to handle some sort of administrative task. Now, the task is done and you don’t need the script anymore. Even so, building the script took a lot of work so you file the script away rather than deleting it just in case you ever need the script again. Now imagine that two or three years have passed and you all of a sudden need that script that you had written so long ago. The problem is, the script is on a network drive with about 100 other scripts that you’ve written over the years. How do you find the script that you need if you can’t remember the filename? Well, if your script contains a header with meaningful information then you can use a search tool to locate the script that you need based on keyword.
Body Comments
Although comments can be very helpful in a script header, the header isn’t the only place within a script where comments should be used. It can be helpful to insert comments into the script body as a way of documenting what various parts of the script do. Even so, you have to be careful about documenting a script.
A couple of months ago I downloaded a PowerShell script from a website because I wanted to see how a particular function had been implemented. As I started looking through the script, I at first thought that I had hit the jackpot because the script was well commented. As I got further into the script however, I began to realize that the author had gone so overboard with the commenting that the comments got in the way of the code.
The script that I was trying to create was only about ten lines long, and I had hoped to use the script that I had downloaded as a model for writing a portion of my script. I extracted the lines of code that I needed from the model script, but they didn’t work. I thought that it seemed kind of odd that a developer would so meticulously document a script that didn’t work, so I tried running the script as the author had written it. The author’s script worked perfectly. Confused, I began working through the script line by line in hopes of figuring out what I had done wrong. What I discovered was that when I extracted code from the script I had missed a line. There were so many comments in the script that the one line of code that I was missing blended in with the comments.
My point is that comments definitely have their place in long PowerShell scripts, but there is such a thing as too much of a good thing. My advice is to add comments to variable declarations, functions, and to any other blocks of code that might be tricky to figure out later on, but don’t try to document every line of code.
In my experience, a script should be written in a way that allows it to be self-documenting. In other words, the script should use meaningful variable names and meaningful function names and be written in a way that leaves absolutely no doubt as to what the script is designed to do.
Conclusion
Using comments in an effective manner can go a really long way toward making a PowerShell script more readable and more intuitive than it would otherwise be. Even so, the best practices for PowerShell scripting go far beyond the use of comments. As I hinted in the previous paragraph, the ways in which you implement functions and variables can have a huge impact on the scripts overall readability. I’m going to spend some time in Part two talking about functions and variables and about why I like using the Set-StrictMode command when I write a lengthy PowerShell script.
If you would like to read the other parts in this article series please go to:
