PowerShell 风格指南

简介

本文提供了一套全面的 PowerShell 编码风格指南，重点关注代码的可读性、一致性及最佳实践，旨在帮助开发者编写清晰、规范、易于维护的脚本。本指南参考自 PowerShell Practice and Style Guide。

代码布局与格式化

保持布局一致性

统一使用缩进、行长度及大小写规范，以提升代码可读性。

大小写规范

所有公共标识符使用 PascalCase。
语言关键字使用 小写字母。
注释式帮助中的关键字使用 大写字母。

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

标准括号风格 (OTBS)

左括号 { 放在代码行末，右括号 } 单独占一行。

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

CmdletBinding 与代码块顺序

函数应以 [CmdletBinding()] 开始，按顺序使用 param(), begin, process, end。

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

缩进

每个缩进层级使用四个空格。

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

最大行长度

建议每行不超过 115 个字符。使用 splatting 或括号优化换行。

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

空行与空格

函数前后保留两行空行。
禁止行尾多余空格。
操作符与参数前后使用一个空格。

$Value = 5 + 3

避免使用分号

不建议使用分号 ; 作为行结束符。

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

函数规范

基本函数

避免使用 return，直接输出对象。
函数名与参数列表之间留一个空格。

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

高级函数

命名采用 <动词>-<名词> 格式。
必须使用 [CmdletBinding()]。
返回对象应在 process {} 块中。
指定 OutputType。

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

文档与注释

注释规范

注释需保持及时更新。
使用英文，必要时写完整句子。
说明设计意图与决策，避免解释显而易见的代码。

# 由于界面重叠，调整边距
$Margin = $Margin + 2

块注释

长注释使用 # 或 <# ... #> 格式。

<#
    .SYNOPSIS
        块注释示例。
#>

行内注释

对齐行内注释，提升可读性。

$Options = @{
    Margin = 2      # 界面调整
    Padding = 2     # 文本周围留白
}

注释式帮助

为脚本与函数添加帮助说明。

function Get-Example {
    <#
    .SYNOPSIS
        获取示例数据。
    .EXAMPLE
        Get-Example
    #>
}

可读性优化

代码缩进

正确缩进，清晰展示代码结构。

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

避免使用反引号 (“`)

换行时优先使用 splatting，避免反引号带来的问题。

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

命名规范

使用完整的命令与参数名

避免使用别名或缩写。

Get-Process -Name Explorer

使用明确路径

推荐使用完整路径或 $PSScriptRoot。

Get-Content "$PSScriptRoot\README.md"

避免使用 ~

建议使用 ${Env:UserProfile} 替代 ~。

cd ${Env:UserProfile}

结论

遵循以上指南，可确保您的 PowerShell 脚本更加规范、易读且便于维护，尤其适用于团队协作开发环境。

更多详情请参考 PowerShell Practice and Style Guide。