PowerShell Best Practices

Analogy categoryAnalogies

Writing Scripts That Scale

PowerShell rewards consistency more than cleverness. Using approved verbs (Get, Set, New, Remove) with a singular PascalCase noun, as in Get-UserReport or Remove-StaleSession, means another engineer can guess what a function does before reading a line of its body, and Get-Verb keeps you from inventing a synonym like Retrieve- or Fetch- that breaks discoverability through Get-Command.

🏏

Cricket analogy: It is like commentators always saying 'on strike' and 'run out' instead of inventing new phrases each match — a fixed vocabulary like Virat Kohli 'nudges one to deep square leg' lets any fan follow the game instantly.

Parameter Design and Pipeline Support

A well-designed function declares [CmdletBinding()] to get common parameters like -Verbose and -ErrorAction for free, marks required inputs with [Parameter(Mandatory)], and constrains values with [ValidateSet()] or [ValidateRange()] so bad input fails fast with a clear message instead of causing a cryptic error three lines later. Accepting pipeline input via ValueFromPipeline or ValueFromPipelineByPropertyName lets your function compose with Get-Process, Get-ADUser, or any other cmdlet the way the shell was designed to be used.

🏏

Cricket analogy: It is like a fielding restriction rule in T20 cricket that mandates two fielders inside the circle during powerplay — the constraint is enforced automatically by the umpire rather than trusted to the captain's memory.

Comment-Based Help

Every reusable function should ship with comment-based help — a block starting with <# and containing .SYNOPSIS, .DESCRIPTION, .PARAMETER, and at least one .EXAMPLE — placed directly above or inside the function. Once that block exists, Get-Help Get-UserReport -Full renders it exactly like built-in cmdlet documentation, which means new team members can self-serve instead of pinging the author on Slack every time they forget a parameter name.

🏏

Cricket analogy: It is like a scorecard that includes not just runs but strike rate and fall-of-wickets detail, so anyone reading it later understands the full context of the innings without watching the replay.

Error Handling and Idempotency

Most cmdlet errors are non-terminating by default, so a try/catch block around them does nothing unless you force termination with -ErrorAction Stop or set $ErrorActionPreference = 'Stop' for the scope. Inside catch, use $_.Exception.Message and $_.InvocationInfo.ScriptLineNumber to log a precise cause, and prefer writing scripts that check current state before acting — for example testing Test-Path before New-Item, or Get-Service before Set-Service — so re-running the script twice produces the same end state instead of throwing on the second run.

🏏

Cricket analogy: It is like a third umpire reviewing a run-out only when the on-field umpire explicitly refers it — most close calls are accepted as-is, and only a forced review stops play to get certainty.

powershell

function Get-UserReport {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string]$SamAccountName,

        [ValidateSet('Basic', 'Full')]
        [string]$Detail = 'Basic'
    )

    process {
        try {
            $user = Get-ADUser -Identity $SamAccountName -Properties * -ErrorAction Stop
            [pscustomobject]@{
                Name      = $user.Name
                Enabled   = $user.Enabled
                LastLogon = $user.LastLogonDate
            }
        }
        catch {
            Write-Error "Failed to look up '$SamAccountName': $($_.Exception.Message)"
        }
    }
}

Logging, Testing, and Style

Write-Verbose and Write-Debug produce output only when -Verbose or -Debug is requested, which keeps normal runs quiet while still giving you a diagnostic trail on demand; pair that with Start-Transcript for full session logging in scheduled jobs. Before merging any script, run it through Invoke-ScriptAnalyzer to catch style violations and known anti-patterns automatically, and back nontrivial functions with Pester tests so a refactor that breaks behavior fails in CI rather than in production.

🏏

Cricket analogy: It is like Hawk-Eye tracking every ball silently during a match but only displaying the trajectory overlay when the broadcaster requests a review — the data is always there, shown only on demand.

Install the PSScriptAnalyzer module and run Invoke-ScriptAnalyzer -Path .\script.ps1 -Recurse before every commit. It flags common issues like unapproved verbs, unused variables, and plaintext-password parameters, and many teams wire it into a pre-commit hook or CI pipeline so style drift never reaches main.

Never use Write-Host to emit data you intend a caller to consume — it writes directly to the console host and cannot be captured, piped, or redirected. Use Write-Output (or simply let the object fall through) for pipeline data, and reserve Write-Host strictly for interactive, human-facing status text.

Use approved Verb-Noun naming (check with Get-Verb) so functions are discoverable and predictable.
Declare [CmdletBinding()] and validate parameters with [Parameter(Mandatory)], [ValidateSet()], and friends to fail fast on bad input.
Support pipeline input via ValueFromPipeline/ValueFromPipelineByPropertyName so functions compose naturally with other cmdlets.
Ship comment-based help (.SYNOPSIS, .PARAMETER, .EXAMPLE) so Get-Help documents your code automatically.
Force terminating errors with -ErrorAction Stop when you need try/catch to actually catch, and write idempotent scripts that check state before acting.
Use Write-Verbose/Write-Debug for diagnostics and never Write-Host for pipeline-consumable data.
Run Invoke-ScriptAnalyzer and Pester tests before merging to catch style issues and regressions automatically.