Guide de Style PowerShell

Introduction

Cet article propose un guide de style complet pour PowerShell, axé sur la lisibilité, la cohérence et les bonnes pratiques pour écrire des scripts propres et faciles à maintenir. Ce guide est basé sur le PowerShell Practice and Style Guide.

Mise en Page et Formatage du Code

Maintenir la Cohérence du Code

Utilisez une indentation, une longueur de ligne et des règles de capitalisation cohérentes pour améliorer la lisibilité.

Conventions de Capitalisation

Utilisez PascalCase pour tous les identifiants publics.
Utilisez lowercase pour les mots-clés du langage.
Utilisez UPPERCASE pour les mots-clés dans l’aide basée sur les commentaires.

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

One True Brace Style (OTBS)

Placez les accolades ouvrantes à la fin de la ligne et les fermantes sur une nouvelle ligne.

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

CmdletBinding et Ordre des Blocs

Commencez vos fonctions par [CmdletBinding()] et respectez l’ordre param(), begin, process, end.

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

Indentation

Utilisez quatre espaces par niveau d’indentation.

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

Longueur Maximale des Lignes

Limitez vos lignes à 115 caractères. Utilisez le splatting ou des parenthèses pour les retours à la ligne.

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

Lignes Vides et Espaces

Entourez vos fonctions de deux lignes vides.
Évitez les espaces en fin de ligne.
Mettez un espace autour des opérateurs et des paramètres.

$Value = 5 + 3

Évitez les Points-Virgules

N’utilisez pas de point-virgule en fin de ligne.

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

Fonctions

Fonctions de Base

Évitez d’utiliser return. Retournez les objets directement.
Laissez un espace entre le nom de la fonction et les paramètres.

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

Fonctions Avancées

Utilisez la convention <Verbe>-<Nom>.
Toujours utiliser [CmdletBinding()].
Retournez les objets dans le bloc process {}.
Spécifiez le type de sortie avec OutputType.

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

Documentation et Commentaires

Règles Générales

Gardez vos commentaires à jour.
Rédigez en anglais avec des phrases complètes si nécessaire.
Expliquez vos choix, pas ce que le code fait.

# Ajuster la marge en raison du chevauchement de l'interface
$Margin = $Margin + 2

Commentaires en Bloc

Utilisez # ou <# ... #> pour des commentaires plus longs.

<#
    .SYNOPSIS
        Exemple de commentaire en bloc.
#>

Commentaires en Ligne

Alignez vos commentaires pour plus de clarté.

$Options = @{
    Margin = 2      # Ajustement de l'interface
    Padding = 2     # Espacement autour du texte
}

Aide Basée sur les Commentaires

Ajoutez toujours de l’aide dans vos scripts.

function Get-Example {
    <#
    .SYNOPSIS
        Récupère des données d'exemple.
    .EXAMPLE
        Get-Example
    #>
}

Lisibilité

Indentez Votre Code

Respectez l’indentation pour une meilleure lisibilité.

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

Évitez les Backticks

Utilisez le splatting au lieu des backticks pour les retours à la ligne.

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

Conventions de Nommage

Utilisez les Noms Complets

Évitez les alias et les abréviations.

Get-Process -Name Explorer

Utilisez des Chemins Explicites

Préférez les chemins complets ou $PSScriptRoot.

Get-Content "$PSScriptRoot\README.md"

Évitez l’Utilisation de ~

Utilisez ${Env:UserProfile} à la place.

cd ${Env:UserProfile}

Conclusion

En suivant ces bonnes pratiques, vos scripts PowerShell seront plus propres, cohérents et faciles à maintenir, surtout en travail d’équipe.

Pour plus de détails, consultez le PowerShell Practice and Style Guide.