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:

 1function Get-BIOSInfo {
 2
 3<#
 4.SYNOPSIS
 5   Retrieves the BIOS information for the local computer.
 6.DESCRIPTION
 7   Get-BIOSInfo is a function that retrieves the BIOS information
 8   from WMI for the local computer.
 9.EXAMPLE
10   Get-BIOSInfo
11.INPUTS
12   None
13.OUTPUTS
14   Win32_BIOS
15#>
16
17    Get-WmiObject -Class Win32_BIOS
18
19}

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.png

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

1help about_Comment_Based_Help

ps-tip2b.png

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.png

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.png

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:

1function Get-BIOSInfo {
2
3    #Attempting to retrieve the BIOS information from the local computer
4    Get-WmiObject -Class Win32_BIOS
5
6}

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:

1function Get-BIOSInfo {
2
3    <#
4        Attempting to retrieve the BIOS
5        information from the local computer
6    #>
7
8    Get-WmiObject -Class Win32_BIOS
9}

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.

µ