Top Four Suggestions for Effective PowerShell Comments
Summary: Microsoft Scripting Guy, Ed Wilson, lists his top four ideas to include in comments in Windows PowerShell scripts.
Microsoft Scripting Guy, Ed Wilson, is here. It is a new week. This one is filled with potential for unlimited new explorations, beginnings of wonderful friendships, and delving into the mysteries of long forgotten books. Well OK, I actually began the new week yesterday—but still, there is lots to discover about Windows PowerShell.
The weather continues to be absolutely fabulous here in Charlotte, North Carolina. The days are almost perfect. In fact, the weather is so glorious that I had to buy a new pair of running shoes because I wore out the old pair. (Actually, it took me three years to wear out the old pair, but I am hoping to make these obsolete in a few months.)
Anyway, I received a lot of good feedback about yesterday's post, Six Comments about PowerShell Commenting, so I decided I would add a bit more to the list. If you have not read yesterday’s post, it would be a good idea to spend a few minutes reviewing it prior to plunging into today’s.
Yesterday’s post was mostly do not do this or that. I did offer my cardinal positive recommendation, which is: include the intent of the script. Here are more positives (things you should include in your script).
Add a link to the original source.
If you base your script on a script you found in the TechNet Script Repository, PoshCode, or the Hey, Scripting Guy! Blog, you should add a note and a link in your comments. This is not only to be polite (although it really IS polite to give people credit where credit is due), but it is so you know the original source.
In the case of the Hey, Scripting Guy! Blog, I always explain how a script works. So if in making changes, things no longer work as expected (that is, you broke the script), you can go back to the original source and maybe find hints that will help you make it work as expected (that is, fix what was broken).
Quite often the scripts from the script repositories are heavily commented or someone has posted a comment that tells how to modify or change the original. Here is an example of such Q & A:
Add a link to new things you discover.
Quite often, my process of writing Windows PowerShell scripts involves trips to MSDN to read documentation on how a specific .NET object behaves or to find examples of how a particular API works. When I do this, it is because I do not know something.
It is also a good bet that if I need to use that object again in the future, I do not know all of the method overloads, constructors, or enumeration values. Having a link to the specific reference documentation in my script can save me minutes at a minimum (and hours in some cases) when it comes time to modify my script.
Add ideas for future modification.
When I am working on a script, it is because I want to solve a particular problem. This also means that when the script is finished, I need to run the script to solve the problem that necessitated the script in the first place. But what often happens, is that while I am writing the script, I get an idea for a way I could add additional capabilities to the script. Therefore, I could make it a more general purpose tool, rather than single purpose, disposable code. But because I am working against a clock to solve a specific problem, I do not have time to explore this rabbit trail. I add comments to remind me what I can do in the future.
Use a #TODO tag.
If a script is functional, but it is incomplete, use a standard tag (such as #TODO) to facilitate searching for work items. It then becomes trivial to use the Select-String cmdlet to search for outstanding work items in all Windows PowerShell scripts that are in a specific folder, drive, or network location. Even better is to write a Windows PowerShell add-in that will standardize adding #TODO tags in a consistent way to facilitate such searching. Here is an example of such a search:
PS C:\> Select-String -Path c:\fso\* -Pattern '#TODO'
fso\myscript.ps1:1:#TODO add descriptive comments to the script
That is all there is to adding and using comments in Windows PowerShell scripts. Join me tomorrow when I will talk about more cool 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
Light
Dark
0 comments