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 from your scripts that you can. 

Comment-Based Help is 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:

function OpenClosePorts {
<#
.SYNOPSIS 
Create, modify, or toggle a firewall rule
.DESCRIPTION
Create, modify, or toggle a firewall rule
Set the parameters for the new rule.
If a rule with the specified name exists > Update the rule to match the new parameters 
If a rule with the specified name does not exist > create a new firewall rule with the specified parameters
.PARAMETER DisplayName
Specifies the name of the firewall rule to be modified
.PARAMETER LocalPort
(Optional) Specify the port affected by the firewall rule
.PARAMETER Direction
(Optional)Specify if the connection is Inbound or Outbound. (Default = Inbound)
.PARAMETER Action
(Optional) Select if you want to Allow or Block a connection. (Default = Allow)
.PARAMETER Exists
(Optional) Enable or Dissable the rule. True/False (Default = True)
#>
param (
        [string]$DisplayName = "Test",$LocalPort = 8626, [string]$Direction = "Inbound",[string]$Action = "Allow",$Exists = $true
    )
    $CheckRule = Get-NetFirewallRule -DisplayName $DisplayName 2> $null
    
    if ($CheckRule){
        Set-NetFirewallRule -DisplayName $DisplayName `
        -LocalPort $LocalPort `
        -Direction $Direction `
        -Protocol TCP `
        -Action $Action `
        -Enabled $Exists.ToString()
        }
    else {
        New-NetFirewallRule -DisplayName $DisplayName `
        -LocalPort $LocalPort `
        -Direction $Direction `
        -Protocol TCP `
        -Action $Action `
    }
}

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:

Name 
OpenClosePorts 

SYNOPSIS 
Create, modify, or toggle a firewall rule

DESCRIPTION
Create, modify, or toggle a firewall rule
Set the parameters for the new rule.
If a rule with the specified name exists > Update the rule to match the new parameters 
If a rule with the specified name does not exist > create a new firewall rule with the specified parameters

PARAMETER 
DisplayName
             Specifies the name of the firewall rule to be modified

             Required?                  true
             Position?                    0
             Default value
             Accept pipeline input?       false
             Accept wildcard characters?

LocalPort
		(Optional) Specify the port affected by the firewall rule

		          Required?                  false
            	Position?                    0
            	Default value
             	Accept pipeline input?       false
             	Accept wildcard 
...

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.

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 and 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 the 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.

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.

Get Started

Comment-based help enables every definition of self-service and if you’re not using it, you’re doing yourself a disservice. When using Otter, simply adding some extra details takes your scripts to the next level of functionality and extends their lifespan by years.