Руководство по стилю PowerShell

Введение

Это руководство предлагает полный свод правил по стилю PowerShell, с акцентом на читаемость, последовательность и лучшие практики для написания чистых и легко сопровождаемых скриптов. Руководство основано на PowerShell Practice and Style Guide.

Оформление и форматирование кода

Соблюдайте единый стиль

Используйте единообразную структуру отступов, длину строк и правила написания с заглавной буквы для улучшения читаемости.

Правила написания с заглавной буквы

• Используйте PascalCase для всех публичных идентификаторов.
• Используйте lowercase для ключевых слов языка.
• Используйте UPPERCASE для ключевых слов в комментариях справки.

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

Стиль скобок (One True Brace Style — 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.