Comment‑Based Help¶

Professional PowerShell scripts must be self‑documenting. A script that performs important administrative tasks but lacks documentation becomes difficult to maintain, risky to modify, and nearly impossible for another administrator to understand months or years later. PowerShell solves this problem through comment‑based help, a built‑in documentation system that allows you to embed structured help directly inside your script or function.

Comment‑based help is not optional in professional environments—it is a core requirement. It ensures that anyone running your script can access clear, accurate instructions using the same Get-Help system that PowerShell uses for built‑in cmdlets.

This section explains how comment‑based help works, how to structure it, and how to write documentation that is both complete and easy to understand.

1. What Comment‑Based Help Is¶

Comment‑based help is a block of specially formatted comments placed inside a script or function. PowerShell reads these comments and exposes them through the Get-Help cmdlet.

This means:

Your script behaves like a native PowerShell cmdlet
Users can run Get-Help .\MyScript.ps1
Help is available even without opening the script file
Documentation stays synchronized with the code

Comment‑based help transforms a script from a collection of commands into a professional tool.

2. Where Comment‑Based Help Goes¶

Comment‑based help can be placed in two locations:

At the top of a script file — documents the entire script
Inside a function — documents that specific function

For scripts, the help block appears before any executable code.

For functions, it appears immediately before the function keyword or inside the function as the first item.

3. Structure of a Comment‑Based Help Block¶

A help block uses a <# … #> comment and contains sections introduced by dot‑prefixed keywords. The most common sections are:

.SYNOPSIS — a one‑sentence summary
.DESCRIPTION — a detailed explanation
.PARAMETER — documentation for each parameter
.EXAMPLE — usage examples
.NOTES — additional information
.INPUTS and .OUTPUTS — types accepted and returned
.LINK — related commands or documentation

Not all sections are required, but .SYNOPSIS, .DESCRIPTION, and .EXAMPLE should always be included.

4. Example of Comment‑Based Help for a Script¶

Below is a complete, professional help block for a script that creates new users from a CSV file:

<#
.SYNOPSIS
    Creates new Active Directory user accounts from a CSV file.

.DESCRIPTION
    This script reads user information from a CSV file and creates
    Active Directory accounts with standardized attributes. It supports
    secure password handling, OU placement, and optional logging.

.PARAMETER Path
    The path to the CSV file containing user information. The file must
    include Name, SamAccountName, and Password columns.

.PARAMETER LogPath
    Optional. If provided, the script writes a log of all created accounts
    to the specified file.

.EXAMPLE
    .\New-ADUsers.ps1 -Path "C:\Data\Users.csv"

.EXAMPLE
    .\New-ADUsers.ps1 -Path "C:\Data\Users.csv" -LogPath "C:\Logs\creation.log"

.NOTES
    Author: Enrico Rossi
    Version: 1.3
    Requires: ActiveDirectory module
#>

This block provides everything an administrator needs to understand and use the script safely.

5. Comment‑Based Help for Functions¶

Functions should also include help, especially if they are part of a module or reused across scripts.

Example: function help¶

function New-EmployeeAccount {
<#
.SYNOPSIS
    Creates a new Active Directory user account.

.DESCRIPTION
    This function creates a new AD user with the specified name,
    username, and password. It does not enable the account unless
    explicitly requested.

.PARAMETER Name
    The display name of the user.

.PARAMETER SamAccountName
    The logon name for the user.

.PARAMETER Password
    A secure string representing the user's password.

.EXAMPLE
    New-EmployeeAccount -Name "Alice Kim" -SamAccountName "alice.kim" -Password $pwd
#>

    param(
        [string]$Name,
        [string]$SamAccountName,
        [securestring]$Password
    )

    New-ADUser -Name $Name -SamAccountName $SamAccountName -AccountPassword $Password
}

This ensures that anyone using the function—whether in your script or in a module—can access help directly.

6. How PowerShell Uses Comment‑Based Help¶

Once help is embedded, PowerShell exposes it through the standard help system.

Viewing help for a script¶

Get-Help .\New-ADUsers.ps1

Viewing help for a function¶

Get-Help New-EmployeeAccount

Viewing examples only¶

Get-Help .\New-ADUsers.ps1 -Examples

Viewing full help¶

Get-Help .\New-ADUsers.ps1 -Full

This makes your script feel like a built‑in cmdlet.

7. Best Practices for Writing Comment‑Based Help¶

To ensure your help is clear and professional:

Write the synopsis as a single, concise sentence
Use the description to explain the script’s purpose and behavior
Document every parameter, even optional ones
Provide multiple examples, covering common scenarios
Keep help synchronized with script updates
Use clear, formal language
Avoid abbreviations unless they are standard in your environment

Good help is not an afterthought—it is part of the script’s design.

8. Summary¶

Comment‑based help is a foundational element of professional PowerShell scripting. It transforms scripts into self‑documenting tools by providing:

Clear explanations of purpose and behavior
Detailed parameter documentation
Practical usage examples
Integration with the Get-Help system
Maintainability for future administrators

By consistently including comment‑based help, you ensure that your scripts are understandable, safe to use, and aligned with professional standards.