Final Comments about PowerShell Comments
Summary: Microsoft Scripting Guy, Ed Wilson, concludes the series of posts about adding comments to Windows PowerShell scripts. Microsoft Scripting Guy, Ed Wilson, is here. This morning, I am sipping a cup of Assam tea. It is rich, robust, and has a very nice flavor. I add a bit of lemon juice and a cinnamon stick to balance out the flavor. I also have a piece of dark chocolate that seems to go exceptionally well with the tea. With tea, it is all about balance. In a way, it is the same with adding comments to a Windows PowerShell script.
Five Ws and an H
Comments help make the script easy to understand. I like to visualize myself six months from now. What will I be doing? What will be going on? When I look at this script will I even recognize what I wrote? Will I understand the script? Will I know what I was thinking? What about what I was trying to accomplish? I then seek to answer these sorts of questions. To help me make sure that I add good comments, I like to think about the “five Ws and the H.” The five Ws and the H are taught to first year journalism students (even in beginning writing classes) as a good way to help to include everything that needs to be said in a document. The five Ws and H are: Who, What, When, Where, Why, and How. If you address each of these in your comments, you will go a long way towards making your script easier to understand. Here are some of the things I think about with my script as I review the five Ws and H:
- Who
Who wrote the script? It is always a good idea to add the author and appropriate contact information for scripts that are used internally—or if you want to let people know who wrote the script.
Also think about who runs the script. Does the script require admin rights? Is there a special account that is used when running the script? Is the script a Help Desk script or an admin script? All of these thoughts come under the heading of Who. - What
What does the script do? What does it need? Does the script need, for example the SQL Server Management Pack to run properly? Or does it need access to the Azure cmdlets? All of these thoughts come under the heading of What. - When
When does the script run? Is it something that runs via a scheduled task (the Windows Task Scheduler or as a Windows PowerShell scheduled job)? Is the script normally run at the end of the month, or the end of the week, or after a server is built? All of these thoughts come under the heading of When. - Where
Where does the script run from? Where are the target servers? This is really important to document when talking about workflow and DSC scripts. - Why
Why was the script written? Why are particular coding conventions used? Why does the script require Windows PowerShell 2.0 instead of the latest version? All of these sorts of thoughts are Why types of questions. - How
How is the script run? How can it be improved? How is the script deployed?
The number one rule…above all else…regardless of anything else is this: Make the script easy to understand. That is it. Make the script easy to understand—especially six months or a year from now. Whoever is tasked with fixing it, modifying it, or optimizing it will thank you. Hey, the way things go, it will probably be you. So do yourself a great big favor, and write excellent comments. They may very well come in handy. To read more about comments in Windows PowerShell, see:
- Six Comments about PowerShell Commenting
- Top Four Suggestions for Effective PowerShell Comments
- Use Regions for PowerShell Comments
- More Comments about PowerShell Commenting
That is all there is to using Windows PowerShell comments. Join me tomorrow when we will have 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