PowerShell Tip #2 from the Winner of the Advanced Category in the 2013 Scripting Games

Tip #2 – Comment (Document) your code!

This is another one of those tips that probably isn’t very popular, but regardless of how good you are at writing PowerShell scripts and functions, they’re useless if no one else can figure out how to use them. You might be thinking that you’re the only one who uses the PowerShell code that you write, but I’m sure that you like to go on vacation just like the rest of us and none of us are going to live forever.

In my tip #1 blog you learned that you need to “Read the Help!”. This tip builds on the first one because it allows others to “Read the Help!” for the PowerShell code that you write.

The type of help that you want to provide for your PowerShell functions and scripts is “Comment Based Help”. Here’s a simple example of a function with comment based help:

That little bit of information, when formatted properly, allows the user of this function to retrieve help for it just as they would for a cmdlet:

ps-tip2a

See the “about_Comment_Based_Help” help topic for more details (read the help):

ps-tip2b

If you’re using the PowerShell ISE (Integrated Scripting Environment), the “Cntl + J” key combination will bring up code snippets and the first two options include the syntax for functions. They also include the syntax for comment based help:

ps-tip2c

If you use the previous code snippet from the ISE, be sure to change the “.Synopsis” keyword to all caps since all of the other keywords are in all caps (be consistent).

If you happen to be using SAPIEN PowerShell Studio, the key combination to bring up code snippets is “Cntl + K”:

ps-tip2d

Unlike the ISE, there’s a snippet in PowerShell Studio that is specifically for “Comment Based Help” and as you can see, the case of all the keywords is consistent (in all caps).

Inline help is another type of help as shown in the following example:

Single line inline help comments begin with an Octothorpe. Yeah, I’d never heard of a pound or hash sign being called that either until I was listening to one of the PowerScripting podcast episodes.

Block comments use angle braces and octothorpes. They are multi-line inline comments:

The problem is that inline help is absolutely useless because it will never be seen unless someone manually opens up your script and reads through it. Who really wants to read through hundreds or possibly even thousands of lines of code looking for comments? Maybe your turning this tool over to your help desk personnel and maybe they don’t know much about PowerShell other than how to open the console and run certain commands. Do you really want them opening up your scripts and digging around in them looking for comments if they need help? With that said, don’t use line help because there’s a better way which I’ll cover in my next blog article (tip #3).

Last but not least, comment but don’t over comment. You’re not writing literature.

µ

Leave a Reply

%d bloggers like this: