PowerShell Styleguide

Einführung

Dieser Artikel bietet einen umfassenden PowerShell-Styleguide mit Fokus auf Lesbarkeit, Konsistenz und Best Practices für die Erstellung von sauberen und leicht wartbaren Skripten. Dieser Leitfaden basiert auf dem PowerShell Practice and Style Guide.

Code-Layout & Formatierung

Konsistenz im Layout wahren

Sorgen Sie für einheitliche Einrückungen, Zeilenlängen und Groß-/Kleinschreibung, um die Lesbarkeit zu verbessern.

Groß- und Kleinschreibungsregeln

• Verwenden Sie PascalCase für alle öffentlichen Bezeichner.
• Verwenden Sie lowercase für Sprachschlüsselwörter.
• Verwenden Sie UPPERCASE für Schlüsselwörter in Kommentar-basierten Hilfen.

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

One True Brace Style (OTBS)

Setzen Sie geschweifte Klammern am Ende der Zeile bzw. an den Anfang einer neuen Zeile.

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

CmdletBinding und Block-Reihenfolge

Beginnen Sie Funktionen mit [CmdletBinding()] und verwenden Sie die Reihenfolge param(), begin, process, end.

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

Einrückung

Verwenden Sie vier Leerzeichen pro Einrückungsebene.

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

Maximale Zeilenlänge

Begrenzen Sie Zeilen auf 115 Zeichen. Nutzen Sie Splatting oder Klammern für saubere Zeilenumbrüche.

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

Leerzeilen und Leerzeichen

• Zwei Leerzeilen vor und nach Funktionen.
• Keine Leerzeichen am Zeilenende.
• Ein Leerzeichen um Operatoren und Parameter.

$Value = 5 + 3

Vermeiden Sie Semikolons

Verwenden Sie keine Semikolons als Zeilenabschluss.

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

Funktionen

Basisfunktionen

• Vermeiden Sie return. Geben Sie Objekte direkt aus.
• Lassen Sie ein Leerzeichen zwischen Funktionsnamen und Parametern.

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

Erweiterte Funktionen

• Verwenden Sie das Schema <Verb>-<Noun>.
• Immer [CmdletBinding()] nutzen.
• Rückgaben im process {} Block.
• Definieren Sie OutputType.

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

Dokumentation und Kommentare

Allgemeine Kommentarrichtlinien

• Kommentare aktuell halten.
• Auf Englisch in vollständigen Sätzen schreiben.
• Entscheidungen und Gründe dokumentieren, nicht den Code erklären.

# Rand wegen UI-Anpassung erhöhen
$Margin = $Margin + 2

Blockkommentare

Verwenden Sie # oder <# ... #> für längere Kommentare.

<#
    .SYNOPSIS
        Beispiel für einen Blockkommentar.
#>

Inline-Kommentare

Richten Sie Inline-Kommentare für bessere Lesbarkeit aus.

$Options = @{
    Margin = 2      # UI-Anpassung
    Padding = 2     # Abstand zum Text
}

Kommentar-basierte Hilfe

Fügen Sie stets eine Hilfe zu Ihren Skripten hinzu.

function Get-Example {
    <#
    .SYNOPSIS
        Beispiel-Daten abrufen.
    .EXAMPLE
        Get-Example
    #>
}

Lesbarkeit

Code einrücken

Innerhalb von Strukturen sauber einrücken.

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

Backticks vermeiden

Nutzen Sie Splatting statt Backticks für Zeilenumbrüche.

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

Namenskonventionen

Verwenden Sie vollständige Befehls- und Parameternamen

Vermeiden Sie Aliase und Abkürzungen.

Get-Process -Name Explorer

Verwenden Sie explizite Pfade

Bevorzugen Sie vollständige Pfade oder $PSScriptRoot.

Get-Content "$PSScriptRoot\README.md"

Vermeiden Sie die Nutzung von ~

Nutzen Sie ${Env:UserProfile} anstelle von ~.

cd ${Env:UserProfile}

Fazit

Die Einhaltung dieser Richtlinien sorgt dafür, dass Ihre PowerShell-Skripte sauber, konsistent und leichter wartbar sind – ideal für die Zusammenarbeit in Teams.

Weitere Informationen finden Sie im PowerShell Practice and Style Guide.