Menu
Free Pack
Download BuildMaster Free Trial

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. 

Otter_CBH

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.

Keyword Description
.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. 

Why Bother

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.

Self-Service

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.

create_job_from_template

Otter can automatically generate a UI around your scripts. It does this in two ways:

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.

Get Started

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. 

I'm ready to try Otter

Topics:ProGetPowerShell

Related Posts

About Inedo

Inedo is a software product company bringing you the "tech behind the tech." Makers of Windows-first, enterprise DevOps tools BuildMaster CI/CD, ProGet private package management, and Otter IaC. Maximize developer time, minimize release risk, and empower stakeholders to bring their vision to life faster, all with the people and technology you have right now

Free e-books

Free CICD Book Free dotnet book free IaC book