What is Comment Based Help and Why Your Scripts Need It
by Crista Perlton, on Jul 5, 2021 5:36:00 AM
Comment-Based Help (CBH) is the best and most effective tool to make the perfect PowerShell script. If you're not using Comment-Based Help, you're simply not getting everything out of your scripts that you can.
Comment-Based Help a collection of descriptions and keywords enclosed in a block comment. Unlike normal comments, PowerShell can read COMMENT-BASED HELP and display it upon request using the “Get-Help” command. CBH can be as simple as adding in a single sentence before the .SYNOPSIS or .DESCRIPTION of a script that describes what it does.
Comment-Based Help Example:
Effective comment-based starts with well-thought-out and clear descriptions of what types of systems the script can be run against, such as desktops or domain controllers. If the script is for a mission-critical, high-availability system, the script will need extra care to maintain, so note that in your .DESCRIPTION as well.
By using the “Get-Help” command, PowerShell is able to read the support information specified in the script, contained within “<#” and “#>”, and then output it as help documentation. The output will be a combination of the descriptions provided by the author and information provided by PowerShell itself.
For example, using “Get-Help” in the script above would result in an output similar to the following:
Comment-based Help Keywords
Here's a cheat sheet for both beginners who are learning and seasoned users that need a reference. The following are the top comment-based help keywords.
|.SYNOPSIS||Short description of the function or script.|
|.DESCRIPTION||Longer, detailed description of the function or script.|
|.PARAMETER||The description of a parameter.|
|.EXAMPLE||A sample command that uses the function or script, optionally followed by sample output and a description.|
|.INPUTS||The .NET types of objects that can be piped to the function or script. You can also include a description of the input objects.|
|.OUTPUTS||The .NET type of the objects that the cmdlet returns. You can also include a description of the returned objects.|
|.NOTES||Additional information about the function or script.|
Microsoft has a full list of all keywords here. But some are so rarely used they're not worth mentioning.
Scripts are company assets and are often utilized by more than the original creator. If you or your team are constantly writing new scripts, you may as well not be using automation should just do everything manually.
Comment-based help ensure your scripts are maintainable for the long term. Simply writing a sentence or two that describes the purpose of a script extends its life. It also ensures the script is able to live on even after the original creator leaves a company.
A major benefit of Comment-based Help is how it integrates with software like Otter. CBH allows running scripts with auto-generated UIs. Instead of trying to make an application out of a script, you can use Otter to run scripts with auto-generated UIs.
Otter can automatically generate a UI around your scripts. It does this in two ways:
- Comment-based Help
- Otter's Job Template feature
Otter lets you add comments and descriptions, which as I’ve stated before, is the key to creating perfect PowerShell scripts.
Using job templates enable self-service, removes time-consuming blockers and empowers junior members to be productive/involved. The next time a team member needs to run a job, even if they don’t have permission to run scripts, they can use the template, which will restrict inputs AND will prompt a reminder when you’ve forgotten to fill out required fields.
Comment-based help enables every definition of self-service and if you're not using it, you're doing yourself a dis-service. When using Otter, simply adding some extra details takes your scripts to the next level of functionality and extends their lifespan by years.