Introduction

Comments in PowerShell are used both for documentation and for temporarily disabling code during testing. The language supports single-line comments, block comments, and comment-based help, and each one solves a slightly different problem.

Single-Line Comments With #

The most common PowerShell comment starts with #. Everything after that symbol on the same line is ignored.

1# Show running services
2Get-Service | Where-Object Status -eq 'Running'
3
4Get-Date # Inline comment

This is the best choice for short explanations or for temporarily turning off one line while you debug.

1$path = 'C:\Logs\app.log'
2
3# Remove-Item $path
4Write-Host "Would delete $path"

That keeps the original command visible without executing it.

Block Comments With # and #>

When you need to comment out several lines at once, use a block comment. Start it with <# and end it with #>.

1<#
2This block is disabled during testing.
3Get-Process
4Get-Service
5Write-Host 'Nothing here will run'
6#>
7
8Write-Host 'Script continues here'

This is much faster than putting # on each line manually.

When Block Comments Are Better

Block comments are especially useful when:

• you are narrowing down a bug in a script
• you want to disable a whole section temporarily
• you are adding a longer explanation than one line can hold

They are also common in comment-based help, which PowerShell understands as documentation metadata.

Comment-Based Help

PowerShell scripts and functions can include help content inside specially placed block comments. This is more structured than ordinary commenting and integrates with Get-Help.

1function Get-Greeting {
2    <#
3    .SYNOPSIS
4    Returns a greeting message.
5
6    .PARAMETER Name
7    Name to include in the greeting.
8    #>
9    param(
10        [string]$Name
11    )
12
13    "Hello, $Name"
14}

If you run Get-Help Get-Greeting, PowerShell can use that information as built-in function help.

Comments Are Not Just for Hiding Code

The best comments explain intent, assumptions, or risks. They should answer "why is this here" more often than "what does this line do."

Weak comment:

# Set count to 5
$count = 5

Better comment:

# Retry limit kept low because the remote API rate-limits aggressively.
$count = 5

The second comment adds information the code itself does not express.

Be Careful With Nested Block Comments

PowerShell does not support nested block comments. If you already have a <# ... #> block inside a region and then wrap a larger outer block around it, the parser can get confused.

That means block comments are convenient, but they are not a perfect replacement for editing with care.

A Debugging Pattern

A practical pattern while debugging is to comment out risky lines but leave visible output in place.

1function Clear-OldLogs {
2    param(
3        [string]$Folder
4    )
5
6    Get-ChildItem $Folder -Filter '*.log'
7
8    # Remove-Item "$Folder\*.log" -Force
9    Write-Host 'Deletion step is currently disabled'
10}

This helps you test the script's flow safely before turning the destructive step back on.

Common Pitfalls

The biggest pitfall is using comments to explain code that should instead be rewritten to be clearer. If every line needs explanation, the script structure probably needs work.

Another issue is leaving large commented-out blocks in production scripts indefinitely. Temporary debugging comments that never get cleaned up make maintenance harder.

Developers also forget about nested block comment limitations and accidentally break script parsing while trying to disable a big section quickly.

Finally, do not confuse normal comments with comment-based help. They both use comment syntax, but only help-style blocks follow the expected .SYNOPSIS, .PARAMETER, and related conventions.

Summary

• Use # for single-line and inline comments.
• Use <# ... #> to comment out multiple lines at once.
• Use comment-based help when documenting scripts or functions for Get-Help.
• Prefer comments that explain intent or risk, not obvious code behavior.
• Be careful because PowerShell block comments do not nest.