How to Comment PowerShell Code?

Almost every programming language has a way to add comments to code, and PowerShell is no exception. When you write code in PowerShell, you may find it helpful to add comments to explain what your code does.

Commenting-out code is standard practice when testing and debugging so that that part of the code does not run. There are two types of comment structures in PowerShell — line and block.

Each type has its purpose, but both can be used interchangeably.

In this tutorial, we’ll explain how to comment PowerShell code, including creating comment-based help to add built-in help to your scripts.

Single-Line Comments

Single-line or line comments use simple logic—everything after the # sign in the same line is ignored.

See the example code below:

# Get-Service | Select-Object -First 5 
Get-Process | Select-Object -First 5

The above code has two lines. The first line is commented-out, and as a result, PowerShell will ignore it, and it will not run.

Another way to use line comments is at the end of the line:

Get-Process | Select-Object -First 5 # Return the first five processes.

You could combine the line comments above and after the line like the code below. The first comment on top describes what the code block does, while the end-of-line comments describes the specific line of code.

# Define the certificate details 
$certSplat = @{ 
Subject = 'CN=MailboxQuotaStatus' # Certificate subject 
NotBefore = ((Get-Date).AddDays(-1)) # Validity start date 
NotAfter = ((Get-Date).AddYears(5)) # Expiration date 
CertStoreLocation = "Cert:\CurrentUser\My" # Certificate store location 
KeySpec = "KeyExchange" # Key usage 
Provider = 'Microsoft Enhanced RSA and AES Cryptographic Provider' # Encryption provider 
} 

# Create the Self-Signed certificate 
New-SelfSignedCertificate @certSplat

If you’re using Visual Studio Code to write your code, you can press CTRL+/ to comment out the current line.

Or multiple lines.

Note. Check our tutorial on how to send emails using the Send MailMessage PowerShell cmdlet.

Block Comments

Unlike line comments, block comments enclose one or more lines between <# and #>. PowerShell will ignore everything inside these starting and closing marks. This type of comment makes more sense in some use cases.

Apart from commenting out code, you can use this to split a very long comment into multiple lines. Below is an example of a long comment in a single line:

# This is a very long comment that spans outside the display capacity and goes out of view making it really hard to read.

Long comments can be hard to read because it makes you scroll side to side. To make it easier to read, you can convert it to a block comment and fit it in a narrower frame.

<# 
This is a very long comment that spans 
outside the display capacity and goes 
out of view making it really hard to read. 
#>

Another excellent use of block comments is to have in-code documentation. For example, you can include pre-execution instructions within the script.

<# 
Before running this script, ensure to 
do the following preparations: 

1. Do this. 
2. Do that. 
3. Then whatever. 
#>

You can also use a block comment to embed details in a line of code without breaking the code.

Get-Service -Name <# service name here #> ProfSvc

As you can see, even if the block comment is embedded into the line, PowerShell skips it and the command continues to run successfully.

In Visual Studio Code, you can highlight a line or multiple lines and press SHIFT+ALT+A to turn it into a comment block.

Comment-Based Help

Have you ever wondered how some built-in commands have help systems? For example, Get-Help -Name Get-Content shows you the help system for the Get-Content cmdlet.

You can create the same help system for your scripts and functions by using comment-based help. The Comment-Based help is in the form of a block comment but with defined syntax. Below is an example of a function with comment-based help.

Each help section starts with specific identifiers like “.SYNOPSIS”, “.DESCRIPTION”, ”.PARAMETER”, and ”.EXAMPLE”.

Function SayThisMessage { 
<# 
.SYNOPSIS 
Displays a message on the screen with a color option. 
.DESCRIPTION 
Displays a message on the screen with a color option. 
.NOTES 
This function changes the console text color 
and resets it to default after the message is displayed. 

.PARAMETER Text 
The message to display. Mandatory. 

.PARAMETER Color 
Optional text color. 

.EXAMPLE 
SayThisMessage ` 
-Text "Hello, I'm PowerShell. What can I do for you?" 

Displays a message without changing the console text color. 

.EXAMPLE 
SayThisMessage ` 
-Text "Hello, I'm PowerShell. What can I do for you?" ` 
-Color 'Green' 

Displays a message in green. 
#> 

param( 
[Parameter(Mandatory)] 
$Text, 
[Parameter()] 
$Color = 'Cyan' 
) 

if ($Color) { 
$Host.UI.RawUI.ForegroundColor = $Color 
} 

$Text | Out-Default 
[Console]::ResetColor() 
}

When you import this function in PowerShell, you can display its help system by running the below commands.

Get-Help -Name SayThisMessage 
Get-Help -Name SayThisMessage -Examples 
Get-Help -Name SayThisMessage -Detailed 
Get-Help -Name SayThisMessage -Full 
Get-Help -Name SayThisMessage -Parameter <parameter name>

Conclusion

In conclusion, commenting your PowerShell code is an essential practice that can greatly benefit you and others who may be reviewing or working with your code. Commenting makes your code easier to understand, maintain, and modify, especially when you or someone else comes back to it after some time has passed.

By following the best practices we discussed in this post, such as writing clear and concise comments and avoiding unnecessary comments, you can ensure that your PowerShell code is well-documented and easy to follow.

Remember, commenting is not only a sign of good programming practice, but it also shows respect for your fellow developers and helps build a collaborative and efficient coding environment.