How to comment in PowerShell


In my research on questions people are searching for, I was surprised to find people asking about comments. I’m here to serve. Adding comments to your scripts helps people—including your later self—understand the purpose of your code, what each part of it is doing, and why. Or perhaps you want to temporarily disable some of your code without deleting it, so you can turn the code into a comment until you’re ready to restore it.

How do you comment in PowerShell? Place a # on a line to the left of the comments, or enclose any number of lines with <# and #>.

  • Commenting works the same in Windows PowerShell and PowerShell Core
  • The multiline-capable <# #> block comment was added in PowerShell v2 (you surely have a later version)
  • The # symbol is commonly called pound sign, number sign, or a hash
  • Comments work the same in the PowerShell console as in a script file, which is handy if you paste a script into the console

Where comments can go

The most common and recommended placement of comments is right before the code it describes. Single-line comments with # are commonly perfectly adequate. If you want to go multi-line for longer comments you can put a # in front of each comment line or enclose all of it with <# #>.

# Get the list of running processes
Get-Process

<#
  If I find the need to write more comments,
  like maybe to include author name, dates
  written, revisions and such, a multiline
  block comment might do

  The extra indentation of the text isn't
  necessary, but it looks nice, doesn't it?

  It behaves exactly like Get-Process, except
  it doesn't accept any parameters!
#>
function Get-MyProcess {
    Get-Process
}

    # You can indent comments, too
    # Or have more than one single-line
    # comment instead of a block comment
Write-Output "Hello, World"

Comments can often—but not always, see below—be put after a line of code. This may seem easy and intuitive, and in a syntax-highlighted editor will be clear, but is generally regarded as bad practice.

Get-Process # Get the process list

PowerShell has powerful pipelining which I use all the time, and you can put comments between the pipeline lines.

Get-Process |
    # Sort so the highest-cpu are at the top
    Sort-Object -Descending -Property CPU |
    # List only the first (top) 10
    Select-Object -First 10

You can put comments in a multiline array list. I find this useful to comment out certain items of the list temporarily without deleting them.

@(
    # Woof
    "dog",
    # Meow
    "cat",
    # Wait, elephants are terrible pets
    #"elephant",
    "fish"
)

You can put single-line comments after pipeline symbols, and you can put block comments <# #> in all sorts of weird places, but just don’t, ok?

Get-Process |
    Sort-Object -Descending -Property CPU | # Comment works here
    Select-Object <# block comments can go in weird places #> -First 10

Where comments cannot go

Single-line comments cannot go before code that you want to run. The code becomes part of the comment. The block comment can go before other code, but again, it’s bad practice.

# Some comment  Write-Output "This is no longer code, but now just part of a comment"
<# Don't do this, but FYI it works #> Write-Output "Hello, World!"

You cannot place a comment after a line-continuation backtick `. It will likely throw an error, because to be used as a line continuation, the backtick must be the last character on the line. If you type a backtick followed immediately by a hash `#, PowerShell will just interpret that as a hash and try to execute the comment as the rest of the line’s code. This may result in a thrown error, a prompt for input, or just unexpected behavior depending on the code and intended comment. If you have a backtick, then a space, then a comment—# or <# #>—it will end the line and begin reading the next line as if it’s a new command, and the result will very based on what’s there.

# Working example of continuing a line
# Unless something later in the script fails to parse
Get-Process `
    | Select-Object -First 10

Get-Process `# This will not work as expected
    | Select-Object -First 10

Get-Process ` # This will throw an error for an empty pipe
    | Select-Object -First 10

Commenting in Visual Studio Code

Visual Studio Code (VSCode website), a freely available code editor, is Microsoft’s recommended editor for PowerShell and PowerShell Core.

To highlight or unhighight the current line or all lines of a selection, press control-/. It will prepend a # on every line, or remove it from every line if one is present on every line.

If you wish to block comment <# #> instead, press alt-shift-A to comment or uncomment the highlighted section. Unlike the previous method, the block comment will begin and end where the highlighted selection is, regardless of whether or not it’s at the beginning of a line.

Commenting in PowerShell ISE

Windows PowerShell Integrated Scripting Environment is the PowerShell editor included with Windows PowerShell v2 through v5. Although it has no hotkeys to comment code, you can still comment and uncomment a number of lines quickly.

Press alt-shift (hold both down) and then either the arrow keys or the mouse to position the cursor, and it will select a rectangular area. Anything you start typing will replace the highlighted rectangle and repeat on every highlighted line. So, to comment a block of text I generally position the cursor at the beginning of the line with the home key or mouse, then alt-shift and arrow up or down (or use the mouse) to another beginning of the line and then type #. Since the selection is zero-width—it looks like a really tall cursor—it just prepends a # on each line, thereby commenting them all out.

To uncomment by removing a # from the beginning of many lines, use alt-shift and the arrow keys or mouse to select either all the #s or the beginning of the line, and then hit the del key.

Clearly in this case it’s best to mass-comment by putting the # at the beginning of each line to make it easier to uncomment later.

Making Get-Help document your own functions with comments

Hopefully you are aware of the Get-Help cmdlet which gives you documentation for PowerShell’s built-in cmdlets. But you can use comments to have it document your own code, too! This is especially handy when building modules, or even if you’re just adding functions into others’ PowerShell profiles.

# .Description
# Returns the result of two plus two
function Add-TwoAndTwo {
    2 + 2
}

Get-Help Add-TwoAndTwo

The result:

NAME
    Add-TwoAndTwo

SYNOPSIS


SYNTAX
    Add-TwoAndTwo [<CommonParameters>]


DESCRIPTION
    Returns the result of two plus two


RELATED LINKS

REMARKS
    To see the examples, type: "get-help Add-TwoAndTwo -examples".
    For more information, type: "get-help Add-TwoAndTwo -detailed".
    For technical information, type: "get-help Add-TwoAndTwo -full".

There are several possible help keywords you can specify. The keyword is preceeded by a dot, and the following line is the text for that keyword. I used single-line comments above, but most of the time you see block commenting used for this. It’s also allowable to place the documentation commeting right after the beginning { of the body or right before the ending } of the function body, but almost always I see it just before the function declaration.

Some of the help info is auto-generated from the code, and some is from the comment-based help. The available keywords include synopsis, description, parameter, example, inputs, outputs, notes, link, component, role, functionality, and more. You can include as little or as much as you want. Here is a fuller example:

<#
.Synopsis
   Adds two integers
.Description
   Given two integers, adds them together using the
   '+' operator and returns an integer result
.Parameter Addend1
    This integer defaults to 2 if not specified and
    will be used on the left side of the '+' operator
.Parameter Addend2
    This integer defaults to 3 if not specified and
    will be used on the right side of the '+' operator
.Example
   Add-TwoIntegers -Addend1 5 -Addend2 3
.Example
   Add-TwoIntegers -Addend1 4 -Addend2 8
.Example
   Add-TwoIntegers
.Inputs
    None; use the parameters to alter the addends.
.Notes
    Come to think of it, this function may be redundant
    to the '+' operator, but it makes a good demonstration
    of comment-based help, yes?
#>
function Add-TwoIntegers {
    [CmdletBinding()]
    [OutputType([int])]
    param(
        [int]$Addend1 = 2,
        [int]$Addend2 = 3
    )
    $Result = $Addend1 + $Addend2
    Write-Output $Result
}

Get-Help Add-TwoIntegers -Full
<#

    Compare to:

Get-Help Add-TwoIntegers -Detailed
Get-Help Add-TwoIntegers -Examples
Get-Help Add-TwoIntegers

#>

The result:

NAME
    Add-TwoIntegers
    
SYNOPSIS
    Adds two integers
    
    
SYNTAX
    Add-TwoIntegers [[-Addend1] <Int32>] [[-Addend2] <Int32>] [<CommonParameters>]
    
    
DESCRIPTION
    Given two integers, adds them together using the '+' operator and returns an integer result
    

PARAMETERS
    -Addend1 <Int32>
        This integer defaults to 2 if not specified and will be used on the left side of the '+' operator
        
        Required?                    false
        Position?                    1
        Default value                2
        Accept pipeline input?       false
        Accept wildcard characters?  false
        
    -Addend2 <Int32>
        This integer defaults to 3 if not specified and will be used on the right side of the '+' operator
        
        Required?                    false
        Position?                    2
        Default value                3
        Accept pipeline input?       false
        Accept wildcard characters?  false
        
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see 
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). 
    
INPUTS
    None; use the parameters to alter the addends.
    
    
OUTPUTS
    System.Int32
    
    
NOTES
    
    
        Come to think of it, this function may be redundant
        to the '+' operator, but it makes a good demonstration
        of comment-based help, yes?
    
    -------------------------- EXAMPLE 1 --------------------------
    
    PS C:\>Add-TwoIntegers -Addend1 5 -Addend2 3
    
    
    
    
    
    
    -------------------------- EXAMPLE 2 --------------------------
    
    PS C:\>Add-TwoIntegers -Addend1 4 -Addend2 8
    
    
    
    
    
    
    -------------------------- EXAMPLE 3 --------------------------
    
    PS C:\>Add-TwoIntegers
    
    
    
    
    
    
    
RELATED LINKS

For more details on using comments to enhance Get-Help with your own code, see About Comment Based Help at Microsoft’s doc site.

If you found this article useful, consider reading my article here on -joining strings in PowerShell.

Recent Content

© 2020 Copyright Practical Code Use