Guida di Stile PowerShell

Introduzione

Questo articolo fornisce una guida completa allo stile di PowerShell, con un focus sulla leggibilità, coerenza e migliori pratiche per scrivere script puliti e facilmente manutenibili. La guida si basa sul PowerShell Practice and Style Guide.

Layout e Formattazione del Codice

Mantieni la Coerenza nel Layout

Utilizza indentazione, lunghezza delle righe e capitalizzazione coerenti per migliorare la leggibilità.

Convenzioni di Capitalizzazione

• Usa PascalCase per tutti gli identificatori pubblici.
• Usa lowercase per le parole chiave del linguaggio.
• Usa UPPERCASE per le parole chiave nell’help basato su commenti.

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

One True Brace Style (OTBS)

Posiziona la parentesi graffa aperta alla fine della riga e quella chiusa su una nuova riga.

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

CmdletBinding e Ordine dei Blocchi

Inizia le funzioni con [CmdletBinding()] e segui l’ordine param(), begin, process, end.

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

Indentazione

Usa quattro spazi per ogni livello di indentazione.

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

Lunghezza Massima della Riga

Limita le righe a 115 caratteri. Usa splatting o parentesi per una corretta gestione delle righe lunghe.

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

Righe Vuote e Spazi

• Inserisci due righe vuote attorno alle funzioni.
• Evita spazi finali nelle righe.
• Usa spazi attorno agli operatori e ai parametri.

$Value = 5 + 3

Evita i Punti e Virgola

Non utilizzare il punto e virgola come terminatore di riga.

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

Funzioni

Funzioni Base

• Evita l’uso di return. Restituisci direttamente gli oggetti.
• Lascia uno spazio tra il nome della funzione e i parametri.

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

Funzioni Avanzate

• Utilizza la convenzione <Verbo>-<Nome>.
• Usa sempre [CmdletBinding()].
• Restituisci oggetti all’interno del blocco process {}.
• Specifica OutputType.

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

Documentazione e Commenti

Linee Guida Generali per i Commenti

• Mantieni i commenti aggiornati.
• Scrivi in inglese con frasi complete se necessario.
• Spiega le decisioni e la logica, non ciò che è ovvio nel codice.

# Regola il margine per sovrapposizione UI
$Margin = $Margin + 2

Commenti a Blocco

Utilizza # o <# ... #> per commenti lunghi.

<#
    .SYNOPSIS
        Esempio di commento a blocco.
#>

Commenti Inline

Allinea i commenti inline per maggiore chiarezza.

$Options = @{
    Margin = 2      # Regolazione UI
    Padding = 2     # Spazio intorno al testo
}

Help Basato su Commenti

Inserisci sempre l’help nei tuoi script.

function Get-Example {
    <#
    .SYNOPSIS
        Recupera dati di esempio.
    .EXAMPLE
        Get-Example
    #>
}

Leggibilità

Indenta il Codice

Applica una corretta indentazione all’interno delle strutture.

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

Evita l’Uso del Backtick

Preferisci lo splatting ai backtick per andare a capo.

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

Convenzioni di Nominazione

Usa Nomi Completi per Comandi e Parametri

Evita alias e abbreviazioni.

Get-Process -Name Explorer

Usa Percorsi Espliciti

Preferisci percorsi completi o utilizza $PSScriptRoot.

Get-Content "$PSScriptRoot\README.md"

Evita l’Uso di ~

Utilizza ${Env:UserProfile} al posto di ~.

cd ${Env:UserProfile}

Conclusione

Seguendo queste linee guida, i tuoi script PowerShell saranno più puliti, coerenti e semplici da mantenere, specialmente in ambienti di lavoro collaborativi.

Per maggiori dettagli, consulta il PowerShell Practice and Style Guide.