Weekend Scripter: What to Include in a PowerShell Comment Block

Summary: Microsoft Scripting Guy, Ed Wilson, talks about what to include in a Windows PowerShell comment block.

Microsoft Scripting Guy, Ed Wilson, is here. Something that tends to confuse new scripters, regardless of the language, is what to include in a comment block at the beginning of a script. I have reviewed thousands of scripts for various scripters, and I have seen lots of variation. This variation ranges from nothing at all, no comments, not a thing to nearly complete books that describe everything a script should do, might do, and even ways to improve the script should it come time for revision.

In reality, your script is, well, your script. How you choose to add a comment block at the beginning of your script is, of course, your business. However, I have found a few things that I think should be in the script header comment block:

1. The name of the script.
   Believe it or not, this is often left off a script. The reason, it seems, is that the file name of the script is the same as the name of the script, and therefore it is redundant information. OK. I can buy that. But at the same time, I like having the name of the script there. It makes it easier for me to identify the script when I am bouncing around between tabs—especially if the name is long. When the name is long, it has a tendency to become truncated on the tab.
2. The author of the script.
   This may seem like a no-brainer, but apparently, it is not. In fact, I have seen many scripts written where no one wants to claim authorship. It is not that the script is a bad script. Rather, they do not want to support the script. It does not matter if you say the script is not supported, people will hunt you down and ask for changes, complain that it does not work in their Windows NT 3.51 environment, or that it blew up their computer's mail implementation.
   I get it...really I do. But when talking about what should be in a script block, clearly the person who wrote the script should include their name. This is really important in a corporate environment, but that is also where I seem to run across the desire to remain anonymous the most. The saying is, “Sure, I have time to write the script, I just do not have time to support it.”
3. Author contact information.
   Of course, if you post to the Internet, you REALLY do not want to include your real email address. But at work, including your email address, and even phone number, is a good idea. It simplifies communication. Of course, this also works in conjunction with item #2.
4. Version of the script.
   I like including a version number. This is especially true when it comes to supporting scripts. If a person says, “The script blew up,” but provides no version information, it is not all that helpful. But if they say, “I have version 1.2 and it blew up,” you can then reply, “Well, you need version 2.0 because I fixed that bug.” Assuming that there really is a version 2.0 and that you really did fix the bug.
5. Where you got the idea.
   If you have a script that is based on a script that you found (for example, on my blog), it is a good idea to include the link to that script. Sure, it is nice to give credit, but from a practical standpoint, it is also a good idea because you will have reference information. On my blog, I include extensive discussion about the script, so information about where I got the code would also include a link to reference information about the script. On the other hand, you may have a link to a site that has lots of other scripts, and you do not want to lose that reference.

Now for things that are nice to have:

1. The version of Windows PowerShell required.
   It is a good idea to include the version of Windows PowerShell. Of course, you can add a #Requires statement at the top of your script, but having it in the comment block is also a good idea.
2. If elevation permissions are required.
   You can add a #Requires statement that indications if elevation is required, but this is a good thing to add to the comment block.
3. If specific modules are required.
   Same as the comments for items #1 and #2.
4. Comments about new types of constructions.
   If you came up with a brilliant idea that you have never used before, it is a good idea to document what you are doing and why.
5. Comments about specific cmdlets.
   Same as the previous comment.
6. Ideas for future improvement of the script.
   If you would like to add additional things to the script, but you did not have time when you were writing it, it makes sense to add a ToDo: section.
7. If there are known errors.
   Most of the time the script may work fine, but occasionally, a script will blow up. If this is a known issue, document it. Of course, you should handle the error, but who knows…

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