powershell.md

PowerShell Conventions

Style

• Approved verbs — Get-, Set-, New-, Remove-, Invoke-, Test-, etc.
• PascalCase for functions and parameters
• $camelCase for local variables
• Explicit parameter names — never positional
• Splatting for commands with 3+ parameters
• Comment-based help on all public functions

Example

function Get-UserHandicap {
    <#
    .SYNOPSIS
        Calculates a golf handicap from scoring differentials.

    .PARAMETER Differentials
        Array of scoring differentials, most recent first.

    .PARAMETER Count
        Maximum number of differentials to consider. Default 20.

    .EXAMPLE
        Get-UserHandicap -Differentials @(10.0, 12.0, 8.0, 11.0)
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [double[]]$Differentials,

        [int]$Count = 20
    )

    $recent = $Differentials | Select-Object -First $Count
    $halfCount = [math]::Floor($recent.Count / 2)
    $best = $recent | Sort-Object | Select-Object -First $halfCount
    $average = ($best | Measure-Object -Average).Average

    [math]::Round($average, 1)
}

Splatting

Use splatting when a command has 3+ parameters:

# Good
$params = @{
    Path        = "C:\logs\app.log"
    Destination = "C:\backup\app.log"
    Force       = $true
}
Copy-Item @params

# Avoid
Copy-Item -Path "C:\logs\app.log" -Destination "C:\backup\app.log" -Force

Testing

• Framework: Pester v5
• File naming: <Module>.Tests.ps1
• Describe/Context/It structure
• Mock external dependencies

Describe 'Get-UserHandicap' {
    Context 'When given four differentials' {
        It 'Returns the average of the best half' {
            $result = Get-UserHandicap -Differentials @(10.0, 12.0, 8.0, 11.0)
            $result | Should -Be 9.0
        }
    }

    Context 'When given a single differential' {
        It 'Returns that differential' {
            $result = Get-UserHandicap -Differentials @(5.5)
            $result | Should -Be 5.5
        }
    }
}

Project Structure

project/
  src/
    Public/
      Get-Something.ps1
    Private/
      Invoke-Helper.ps1
    Module.psm1
    Module.psd1
  tests/
    Module.Tests.ps1
  README.md