PowerShell
What is Comment-Based Help and Why Your Scripts Need It
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.
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 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 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.