Ed Wilson: Developing Windows PowerShell 2.0 Best Practices book

  • Article

While it is true that I have written 3 books on VBScript, I have also written 3 books on PowerShell. I have actually been using Windows PowerShell since before it was publically available, and  therefore I do not  consider myself to be primarily a VBScript guy. In fact, since PowerShell came out, I have written very few VBScripts. I have, however, written thousands PowerShell scripts, including all the scripts for the Windows Vista Resource Kit, Second Edition (2nd edition was PowerShell), Windows Server 2008 Resource Kit , and the Windows 7 Resource Kit . Many of the best practices in the Best Practices book come from having written so many scripts for publication. It is true that my style may differ from some other PowerShell people, but I still consider myself to be primarily a PowerShell guy.

One of the main problems in writing a PowerShell best practices book is the two different ways in which PowerShell can be used. It can be used from the command line, and in those occasions, it is perfectly acceptable to use as short of a syntax as possible -- to reduce the amount of typing. I make extensive use of aliases, and compound dotted notation when I am working interactively at the command line.However, when I am teaching people how to use PowerShell I do not use that syntax because people are struggling with how to use PowerShell.

As to the compound syntax  ... this is a feature of object-oriented programming ... and it could be done in VBScript just as easily as it can be done in PowerShell. I tend to avoid that type of syntax, for several reasons.

  1. It is confusing to others who try to read the script. Sure you can learn to read it, and become familiar with it, but if your script is going to be shared with others (either in your company, or on the internet) it is best to make the script as readable as possible.
  2. It makes for easier troubleshooting. Consider a situation when you are working with an object, and the method call is failing. If you are using a dotted notation, you are not certain whether the method that creates the object that contains the method you are trying to call is available or not. If you store the object in a variable, and then call the method that creates a new object etc. it is easier to understand and easier to troubleshoot.
  3. It promotes code re-use: by storing strings in variables, you are one step away from being able to abstract the entire code into a function that can be used to retrieve information from many registry keys.

When working from the command line, I would use the following on a single line:

(GP HKLM:\SOFTWARE\Microsoft\PowerShell\1\PowerShellEngine).RunTimeVersion

Keep in mind that the focus of the Best Practices book is in scripting, not in command line operations. I often use the command line in examples, because it is quick, but throughout the entire book, the focus is on writing scripts. (In talking about scripts, I am not talking about throw away, one time use scripts, but on scripts that will become part of your automation library.)

But if I were creating a function, that I would be re-using:

Function Get-RunTimeVersion()
{
$path = "HKLM:\SOFTWARE\Microsoft\PowerShell\1\PowerShellEngine"
$psv = Get-ItemProperty -Path $path
$psv.RunTimeVersion
}

One other thing I need to mention about the code I wrote for my Windows PowerShell 2.0 Best Practices book: The Microsoft Press style limits code line lengths to 75 characters. This requires either using lots of variables to reduce the width of the line or using lots of line continuation. Line continuation is very often confusing for people, and therefore use of variables is easier. This also carries over to the Hey Scripting Guy articles  write as well (although not limited to 75 ... it is closer to 85 characters).

This also requires writing narrow code. For my own personal use, I have a wide screen monitor with my resolution set to 1600x900 and therefore personally I like to use wider code ... because it is faster to write. But as a Best Practice, you should write narrow code because when you have to scroll back and forth it makes troubleshooting much more difficult ... AND you do not know what the screen resolution of a persons monitor is. Because the PowerShell console defaults to 80 that should be your default width.

Best Practices are not about what is easiest, they are not even about what is commonly done in the community ... they are about what is the "Best" way to do things. When determining Best Practices these were the big three overall considerations I used. These considerations governed the development of each best practice in my book:

  • What is easiest to read
  • What is easiest to troubleshoot
  • What promotes sharing of scripts

The three best practice considerations build. For example, if a script is easy to read, it will be easier to troubleshoot. If a script is easier to read and to troubleshoot, it is more likely to be shared.

As far as determining the best practices themselves, I consulted a number of sources including the following:

  • I read many books on code development, and examined what they advocated for best practices. (The avoidance of the dotted notation of compound objects was one highlighted in many object-oriented programming books.)
  • I talked to many different Windows PowerShell MVPs.
  • I talked to many different Microsoft people who are in the field working with customers.
  • I talked to many different members of the Microsoft PowerShell team.

In the end, the Windows PowerShell 2.0 Best Practices book is a book that I think does go a long way toward establishing Best Practices for Windows PowerShell. However, keep in mind that in many cases I decided to deviate from the consensus, and in the end, the book as written is my responsibility.