PowerShell Naming Conventions: Best Practices for Scripts and Modules

When I first started writing PowerShell scripts over a decade ago, I quickly realized that consistent naming conventions make a huge difference in code readability and maintainability. Whether you’re writing a simple script or building complex modules, following proper naming standards helps you and your team work more efficiently.

In this article, I’ll share the PowerShell naming conventions I’ve refined over my 10+ years of experience. These practices will help make your scripts more professional, easier to maintain, and simpler to share with others.

Why PowerShell Naming Conventions Matter

Consistent naming conventions provide several key benefits:

• Makes code easier to read and understand
• Reduces debugging time
• Simplifies collaboration with team members
• Helps maintain consistency across projects
• Makes your code more professional

Let’s dive into the specific naming conventions for different PowerShell elements.

PowerShell Cmdlet Naming Convention

PowerShell cmdlets follow a Verb-Noun format by design. Microsoft established this standard, which you should follow when creating your own functions and cmdlets.

Approved Verbs

PowerShell has a list of approved verbs that should be used when naming your cmdlets. You can view this list by running:

Get-Verb

Some common approved verbs include:

• Get: Retrieves data or objects
• Set: Changes the value or properties of an object
• New: Creates a new instance of an object
• Remove: Deletes an object

For example:

• Get-Process
• Set-Location
• New-Item
• Remove-Item

Noun Selection

The noun part should be singular and descriptive of what the cmdlet operates on. It should be specific enough to understand its purpose but not overly complex.

Good examples:

• Get-User (not Get-Users)
• New-VirtualMachine (not New-VM or New-VirtualMachines)

Check out PowerShell Write to File

PowerShell Variable Naming Convention

Variables are an essential part of PowerShell scripting, and naming them properly helps maintain readability throughout your code.

PascalCase vs. camelCase

I recommend using PascalCase for most variables in PowerShell. This means:

• First letter of each word is capitalized
• No spaces or special characters
• Example: $UserName, $ServerCount, $ConnectionString

For loop counters or very temporary variables, camelCase can be acceptable:

• $i, $counter, $tempValue

Descriptive Names

Always use descriptive variable names that clearly indicate what the variable contains:

# Poor naming
$a = Get-Process

# Good naming
$RunningProcesses = Get-Process

Prefixes for Special Variable Types

For certain types of variables, I recommend using prefixes to indicate their type:

• Arrays: $arr or pluralize the name

  $arrServers = @("Server1", "Server2")
  # or
  $Servers = @("Server1", "Server2")

• Hashtables/dictionaries: $hash or a descriptive name ending with “Map”

  $hashConfig = @{Server="localhost"; Port=8080}
  # or
  $ServerConfigMap = @{Server="localhost"; Port=8080}

• Boolean variables: Use $is or $has prefix

  $isEnabled = $true
  $hasPermission = $false

Check out PowerShell Variable Naming Conventions

PowerShell Function Naming Convention

Functions should follow the same Verb-Noun pattern as cmdlets, using approved PowerShell verbs.

function Get-UserDetails {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string]$Username
    )

    # Function code here
}

For private helper functions that won’t be exported from a module, you can prefix them with a verb like “Invoke” or simply use a descriptive name:

function Invoke-DataValidation {
    # Internal function code
}

PowerShell Parameter Naming Convention

In PowerShell, Parameters should follow the PascalCase naming convention, be descriptive, and reflect the data they represent.

function Set-UserProfile {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string]$Username,

        [Parameter()]
        [int]$Age,

        [Parameter()]
        [string]$Department,

        [Parameter()]
        [switch]$ForceUpdate
    )

    # Function code here
}

Common Parameter Patterns

• Use -Force for parameters that override safety checks
• Use -PassThru for cmdlets that would normally not return output
• Use -WhatIf and -Confirm for potentially destructive operations

Check out PowerShell Execution Policy

PowerShell Script Naming Convention

For PowerShell script files (.ps1), I recommend using the following convention:

• Use PascalCase or kebab-case (hyphen-separated words)
• Include the main verb and object in the name
• Be descriptive but concise

Examples:

• Get-SystemInventory.ps1
• Deploy-WebApplication.ps1
• Backup-SqlDatabase.ps1
• system-health-check.ps1

PowerShell Module Naming Convention

For PowerShell modules, use a name that clearly describes the module’s purpose. Avoid generic names that might conflict with other modules.

Good examples:

• CompanyName.ModulePurpose (e.g., Contoso.UserManagement)
• Technology.Component (e.g., SQL.Maintenance)

Avoid excessively long names, but make sure they’re specific enough to identify the module’s purpose.

Check out Reference Variables in PowerShell

PowerShell Constants and Configuration Variables

For constants and configuration values, use all uppercase with underscores separating words:

$MAX_RETRY_COUNT = 5
$DEFAULT_SERVER_PORT = 8080
$API_KEY = "your-api-key"

This makes it easy to identify variables that should not be modified during script execution.

Best Practices for PowerShell Aliases

PowerShell aliases provide shortcuts for cmdlets, but they should be used carefully:

• Never use aliases in scripts or functions meant for others
• Only use well-known aliases in interactive sessions
• Document any custom aliases you create

Common acceptable aliases for interactive use:

• cd for Set-Location
• ls for Get-ChildItem
• ps for Get-Process

Check out PowerShell Array of Strings

Code Example: Putting It All Together

Here’s a script example that follows these naming conventions:

# Get-EmployeeReport.ps1
# This script generates an employee report based on department

# Constants
$DEFAULT_DEPARTMENT = "Sales"
$MAX_EMPLOYEES = 100
$REPORT_PATH = "C:\Reports"

function Get-DepartmentEmployees {
    [CmdletBinding()]
    param (
        [Parameter()]
        [string]$DepartmentName = $DEFAULT_DEPARTMENT,

        [Parameter()]
        [int]$MaxResults = $MAX_EMPLOYEES
    )

    # Function implementation
    $Employees = @()
    # Code to get employees would go here
    return $Employees
}

function Export-EmployeeReport {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [array]$EmployeeData,

        [Parameter()]
        [string]$OutputPath = $REPORT_PATH,

        [Parameter()]
        [switch]$IncludeConfidential
    )

    # Function implementation
    $ReportFile = Join-Path -Path $OutputPath -ChildPath "EmployeeReport.csv"
    # Code to export report would go here
}

# Main script execution
$isDepartmentSpecified = $PSBoundParameters.ContainsKey('Department')
$DepartmentName = if ($isDepartmentSpecified) { $Department } else { $DEFAULT_DEPARTMENT }

$Employees = Get-DepartmentEmployees -DepartmentName $DepartmentName
if ($Employees.Count -gt 0) {
    Export-EmployeeReport -EmployeeData $Employees
    Write-Host "Report generated successfully for $DepartmentName department."
} else {
    Write-Warning "No employees found in the $DepartmentName department."
}

Check out PowerShell Array

PowerShell Comment Conventions

Comments are essential for code documentation. Here are my recommended conventions for PowerShell comments.

Comment Headers

Use comment headers for scripts and functions:

<#
.SYNOPSIS
    Brief description of the script or function.
.DESCRIPTION
    Detailed description of what the script or function does.
.PARAMETER Username
    The username to process.
.EXAMPLE
    Get-UserDetails -Username "JohnDoe"
.NOTES
    Author: Your Name
    Date: January 15, 2023
#>

Inline Comments

For inline comments, place them above the relevant code:

# Check if the user exists before proceeding
if (Test-UserExists -Username $Username) {
    # Additional processing here
}

Following these PowerShell naming conventions has significantly improved my code quality and collaboration with team members. Consistent naming makes code easier to read, understand, and maintain, saving time and reducing errors.

I hope you found this guide helpful. If you have any questions or suggestions about PowerShell naming conventions, feel free to leave them in the comments below.

Other PowerShell articles you may also like:

• PowerShell Where-Object
• PowerShell Global Variables
• Add Quotes in PowerShell
• Create a Log File using PowerShell