Summary: Microsoft Scripting Guy, Ed Wilson, talks about adding comments to Windows PowerShell scripts.
Microsoft Scripting Guy, Ed Wilson, is here. This morning brings another cool fall day in Charlotte, North Carolina. I am sipping a cup of English Breakfast tea with a cinnamon stick and a bit of orange peel in it. I am also munching on a Biscotti. It goes really well with the tea.
One of the most common questions I get from people who are learning Windows PowerShell, is in regards to adding comments to their scripts. I have found lots of people who add lots of comments and even more people who add no comments to their scripts, but it seems somewhat rare to find people who strike an even balance.
Suggestions for effective comments
Do not state the obvious.
If you use a cmdlet to query from WMI, do not have a comment that says you are connecting to WMI and querying the BIOS. It is obvious to just about anyone who reads the script. Here is an example of what not to do:
# connect to WMI and get bios information
Get-WmiObject win32_bios
Do not lie in your comments.
By this, I mean if you have a comment, you should try to be accurate. If you are selecting something (with Select-Object), you can say that you are selecting. But if you are piping the results to Format-Table, you are actually formatting output and not selecting anything at all.
If you are selecting the version, do not state that you are selecting the date (unless the property is actually misleading—that would be a good candidate for a comment anyway). Here is another example of what not to do:
# connect to WMI and get bios information
# select name and date
Get-WmiObject win32_bios | Format-Table Name, Version
Do not add comments at the end of a line.
This is a bit more subtle, but it can make your code easier to write. For example, if I have a comment at the end of a line, and then I want to add a pipeline to do more processing, it means that I now have to move or delete the comment. This can actually lead to errors if one is not careful when editing. It is always better to have a comment precede the code to which it refers. Here is another example of what not to do:
Get-WmiObject win32_bios # connect to WMI and get bios information
Do not add comments after the script.
We are used to reading top to bottom when working with code. So if a comment is important, do not add it after the fact. It is much better to get into the habit of adding comments before the code. Here is what I am talking about not doing:
Get-WmiObject win32_bios
# connect to WMI and get bios information
Do not refer to line numbers in your comments.
After the code is edited, the line numbers may change. You are then stuck with modifying the comments, or having comments that refer to the wrong line. It now makes the code more difficult to read. In the example that follows, I edit the WMI code by adding a pipeline to Format-Table. This occurs after I had added my second comment referring to line 7. Now unfortunately, the previous line 7 is line 8. These sorts of things can quickly become a nightmare.
A good comment describes the intent, not the methodology.
One of the nice things about Windows PowerShell is that it actually rather readable. It is a complete waste of time to say that the Get-WmiObject cmdlet returns a WMI object. Or that Get-Process retrieves processes. But if the comment describes intent, it is much better. For one thing, it can help identify logical errors. If I know what a script is supposed to do, I can easily see if the script actually does what I want it to do. Here is a good comment:
When I read this comment, I can tell exactly what the intent of the script is. I can also see that the script does not meet the intention at all. This is a logic error that would never be found with a debugger. The script works fine, but it does not meet the needs. It returns the version, not the date of the BIOS. It is dubious that the actual name of the BIOS was intended either.
The second command, on my laptop, returns more than the Windows PowerShell ISE process, so that code does not meet my needs either. If I did not have this comment, I would never have known that the script does not work for my situation.
There are lots of other things I could say about adding comments to scripts, but following these six rules will make things a lot better and easier for you in most cases.
That is all there is to adding comments to Windows PowerShell scripts. Join me tomorrow when I will talk about more cool Windows PowerShell stuff.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy