Summary: Microsoft Scripting Guy, Ed Wilson, continues the discussion about Windows PowerShell comments.
Microsoft Scripting Guy, Ed Wilson, is here. This morning, I was up early because I had to take the Scripting Wife to the airport. Luckily, it was really early, so Charlotte’s world class traffic had not yet had a chance to accumulate. She is heading to Long Beach, California to help with registration for Bouchercon 2014.
Bouchercon is a huge conference (sort of like TechEd) devoted to mystery writers and mystery readers. More than likely, she will come back home with a suitcase full of mystery books from newly discovered authors. She is the registration chairperson for Bouchercon 2015, which will be held in Raleigh, North Carolina.
I am really looking forward to that event because I was not able to fly to Long Beach this year. This gives me extra time to play around and work on some of my Windows PowerShell projects that have been piling up. Stay tuned for some really cool stuff.
Must haves in Windows PowerShell comments
There are some situations that definitely call for a comment. I like to think of these situations as answering the following questions:
- What in the world what he thinking about when he wrote this code?
- Why did she do that, when this is so much easier to do?
- I have never seen anything like this in my life. How does this code even work?
- Why is this code commented?
What were they thinking?
I am not talking about explaining the purpose of the script, although that should be done. What I am talking about here is to explain why one constructor is used over another (perhaps relying on the default behavior of the constructor), or why one API is used as opposed to a different one.
This information will be very useful when the constructor changes or a native Windows PowerShell capability becomes available. For example, it is quite common to find Windows PowerShell scripts on the Internet that modify the registry on a remote computer. These were often written with Windows PowerShell 1.0 when Windows PowerShell did not do remoting. To modify the remote registry back then, one usually employed the .NET Framework or WMI. When Windows PowerShell 2.0 brought remoting, neither of these techniques is required (at least by default).
But it may be that the remote servers are running Windows 2000, so using WMI is the only option. A comment about this goes a long way to explain what I was thinking at the time. It also becomes a pointer to a future modification of the script when the remote servers are upgraded to a later operating system.
The script could also modify the registry to ensure a specific configuration of the remote servers (regardless of the methodology). Such a script becomes an immediate candidate to upgrade to using Desired State Configuration (DSC).
Why did they do that?
I see these issues all the time...
A script calls the static NOW method from the System.DateTime .NET Framework class. I always wonder why they did that. Or I find a script that uses the old-fashioned Scripting.FileSystemObject from the VBScript world, or a script that uses Get-WmiObject. Again, I wonder why.
It may be that the reason for using System.DateTime is that it is the only way one knows how to get the current date and time. This becomes obvious when the comment says something like the following:
#getting the current date and time
The reason for using the Scripting.FileSystemObject may be that it is faster and performance is an issue. A note about this would be useful. Many performance improvements have been made in Windows PowerShell 4.0, and if the script is an old one, it may benefit from a new look and performance analysis. A comment such as the following may be useful:
#Get-Content took 15 minutes, switched to ReadAll method and it took 15 seconds.
I’ve never seen this!
If I use a new type of construction or a new feature from the latest build of Windows PowerShell, I like to add a comment about it to explain what is going on. For example, I have seen people who were troubleshooting a script, and they added curly braces to the Where-Object cmdlet. Here is an example of what I am talking about:
#Uses new format of Where-Object
Get-Process | where name -match 'ise'
#Old way of using Where-Object
Get-Process | where { $_.Name -match 'ise'}
Why is this code commented?
When I am troubleshooting a script, I often comment a section of the script. After I finish my troubleshooting, I either delete or uncomment the code in question. Large blocks of commented code, is hard to read, and it is potentially error prone. If a piece of code does not work, but the rest of the script does work, add a note about the current error. Better yet, also add a #TODO tag.
These are some of the questions I think about during a code review, and if the original writer has already provided this documentation, it saves at least a couple of emails, and it may even help avoid the difficulty of scheduling a phone call. Taking the time to add good comments while one is writing a script is a great way to help the script writing and the support processes go quicker, make them cleaner, and be more successful.
There you have it...more about Windows PowerShell comments. Join me tomorrow when I will present my final comments about comments.
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