PowerShell Style Guide

Introduction

This article provides a comprehensive PowerShell style guide focusing on readability, consistency, and best practices for writing clean and maintainable scripts. This guide is based on the recommendations from the PowerShell Practice and Style Guide.

Code Layout & Formatting

Maintain Consistency in Layout

Ensure consistent indentation, line length, and capitalization across your codebase to enhance readability.

Capitalization Conventions

• Use PascalCase for all public identifiers.
• Use lowercase for language keywords.
• Use UPPERCASE for comment-based help keywords.

function Write-Host {
    [CmdletBinding()]
    param(
        [psobject]$Object,
        [switch]$NoNewline
    )
}

One True Brace Style (OTBS)

Place opening braces at the end of a line and closing braces on a new line.

if ($value -gt 0) {
    "Positive"
} else {
    "Non-Positive"
}

CmdletBinding and Block Order

Start functions with [CmdletBinding()] and use param(), begin, process, end in execution order.

[CmdletBinding()]
param ()
process { }
end { }

Indentation

Use four spaces per indentation level.

foreach ($item in $list) {
    Do-Something -Param $item
}

Maximum Line Length

Limit lines to 115 characters. Use splatting or parentheses for clean line breaks.

$Params = @{
    Name = "Explorer"
    Verbose = $true
}
Get-Process @Params

Blank Lines and Whitespace

• Surround functions with two blank lines.
• No trailing spaces.
• Use single spaces around operators and parameters.

$Value = 5 + 3

Avoid Semicolons

Do not use semicolons as line terminators.

$Options = @{
    Margin = 2
    Padding = 2
}

Functions

Basic Functions

• Avoid return. Output objects directly.
• Leave a space between function name and parameters.

function MyFunction ($param1, $param2) {
    ...
}

Advanced Functions

• Use <Verb>-<Noun> naming.
• Always use [CmdletBinding()].
• Return objects in process {} block.
• Specify OutputType.

function Get-Example {
    [CmdletBinding()]
    [OutputType([psobject])]
    param (
        [int]$Id
    )
    process {
        New-Object -TypeName psobject -Property @{ ID = $Id }
    }
}

Documenting and Comments

General Comment Guidelines

• Keep comments updated.
• Write in English, using complete sentences when necessary.
• Explain reasoning, not what the code does.

# Adjust margin due to UI overlap
$Margin = $Margin + 2

Block Comments

Use single-line # or <# ... #> for longer blocks.

<#
    .SYNOPSIS
        Example of block comment usage.
#>

Inline Comments

Align inline comments for clarity.

$Options = @{
    Margin = 2      # Adjust for UI
    Padding = 2     # Space around text
}

Comment-Based Help

Always include help in your scripts.

function Get-Example {
    <#
    .SYNOPSIS
        Retrieves example data.
    .EXAMPLE
        Get-Example
    #>
}

Readability

Indent Your Code

Indent within constructs for clarity.

foreach ($item in $items) {
    Process-Item $item
}

Avoid Backticks

Use splatting instead of backticks for line continuation.

$Params = @{
    Class = "Win32_LogicalDisk"
    Filter = "DriveType=3"
}
Get-WmiObject @Params

Naming Conventions

Use Full Command and Parameter Names

Avoid aliases and short forms.

Get-Process -Name Explorer

Use Explicit Paths

Prefer full paths or $PSScriptRoot.

Get-Content "$PSScriptRoot\README.md"

Avoid Using ~

Use ${Env:UserProfile} instead of ~.

cd ${Env:UserProfile}

Conclusion

Following these guidelines ensures your PowerShell scripts are clean, consistent, and easier to maintain across teams and projects.

For more details, refer to the original PowerShell Practice and Style Guide.