Bonnes pratiques PowerShell : indentation, commentaires et lisibilité

Sophie ouvre un vieux script laissé par un ancien stagiaire : 300 lignes, aucune indentation, aucun commentaire, des variables nommées $a, $b, $x1. « Ce script fonctionne. Mais le jour où il faudra le corriger en urgence à 2h du matin parce qu’un serveur est tombé, personne ne voudra y toucher. » Après plusieurs années à relire et maintenir des scripts écrits par d’autres, cette leçon rassemble les habitudes qui font la vraie différence entre un script qui « marche » et un script qu’on peut faire évoluer sereinement, à plusieurs, dans la durée.

L’indentation : rendre visible la structure

L’indentation n’a aucun impact sur l’exécution d’un script PowerShell — contrairement à Python, un mauvais alignement ne provoquera jamais d’erreur. Mais elle a un impact énorme sur la lisibilité, notamment dès qu’apparaissent des blocs imbriqués (if, foreach, fonctions — vus dans les prochaines leçons).

Comparez ces deux versions strictement équivalentes pour PowerShell :

foreach ($service in $servicesCritiques) {
if ($service.Status -ne "Running") {
Write-Warning "$service est arrêté"
Start-Service -Name $service
}
}

foreach ($service in $servicesCritiques) {
    if ($service.Status -ne "Running") {
        Write-Warning "$service est arrêté"
        Start-Service -Name $service
    }
}

La seconde version permet de voir immédiatement, sans lire une seule ligne, que l’action Start-Service est conditionnée par le if, lui-même contenu dans la boucle foreach. Sur un script de plusieurs centaines de lignes, cette lisibilité devient la différence entre corriger un bug en cinq minutes ou en une heure.

Convention communément admise : 4 espaces par niveau d’indentation (plutôt qu’une tabulation), c’est la recommandation du PowerShell Practice and Style Guide, un guide de référence communautaire largement suivi dans l’écosystème PowerShell professionnel. La plupart des éditeurs modernes (VS Code notamment) convertissent automatiquement la touche Tab en espaces si on le configure ainsi.

Aligner le pipeline sur plusieurs lignes

Un pipeline trop long tient rarement sur une seule ligne lisible. La convention consiste à faire suivre le caractère | d’un retour à la ligne, avec l’indentation qui suit :

Get-Service | 
    Where-Object { $_.Status -eq "Stopped" } | 
    Sort-Object -Property DisplayName | 
    Select-Object -Property DisplayName, Status

Piège fréquent : le caractère | doit impérativement rester en fin de ligne, jamais en début de ligne suivante. PowerShell interprète la fin de ligne comme la fin de l’instruction si le | n’est pas déjà présent pour indiquer que la suite arrive.

Les commentaires : documenter le pourquoi, pas le comment

Un commentaire s’écrit avec # pour une ligne, ou <# ... #> pour un bloc (vu en 5.1 pour l’aide d’un script) :

# Commentaire sur une seule ligne

<#
Commentaire
sur plusieurs lignes
#>

L’erreur la plus courante chez les débutants consiste à commenter des évidences :

# On récupère les services
Get-Service

Ce commentaire n’apporte rien : le code parle déjà de lui-même. Un commentaire utile explique le pourquoi, une information que le code seul ne peut pas transmettre :

# Le service Spooler redémarre parfois seul après une mise à jour Windows :
# on vérifie systématiquement son état avant toute intervention sur l'imprimante réseau.
Get-Service -Name "Spooler"

Retour d’expérience terrain : sur les scripts de production que j’ai pu reprendre après le départ d’un collègue, ce sont systématiquement les commentaires expliquant une décision inhabituelle (« pourquoi ce délai de 30 secondes ici », « pourquoi ce cas particulier est exclu ») qui ont fait gagner le plus de temps — bien plus que des commentaires décrivant simplement ce que fait déjà une ligne de code lisible.

Nommer clairement, plutôt que commenter

Souvent, un bon nom de variable ou de fonction rend le commentaire inutile. Comparez :

$x = Get-Date
$x = $x.AddDays(-30)   # date il y a 30 jours

$dateLimiteArchivage = (Get-Date).AddDays(-30)

La seconde version se passe totalement de commentaire : le nom de la variable porte l’information à lui seul.

Espacer et aérer

Une ligne vide entre deux blocs logiques distincts améliore considérablement la lecture rapide d’un script, exactement comme des paragraphes dans un texte :

$dossierRapports = "C:\Nordika\Rapports"
if (-not (Test-Path $dossierRapports)) {
    New-Item -Path $dossierRapports -ItemType Directory | Out-Null
}

$servicesCritiques = "Spooler", "W32Time", "Dnscache"
foreach ($nomService in $servicesCritiques) {
    Get-Service -Name $nomService
}

Une checklist rapide avant de considérer un script « propre »

Indentation cohérente à 4 espaces par niveau
Un pipeline long est découpé sur plusieurs lignes, | en fin de ligne
Les noms de variables sont explicites ($dateLimiteArchivage, pas $d)
Les commentaires expliquent une décision ou un contexte, pas l’évidence
Un bloc d’aide <# .SYNOPSIS ... #> en tête de script (vu en 5.1)

Ces habitudes ne changent rien à ce qu’exécute PowerShell : un script mal indenté et un script parfaitement structuré produisent exactement le même résultat. La différence se joue entièrement sur la maintenance future — la vôtre dans six mois, ou celle d’un collègue de Nordika qui découvre le script pour la première fois.

Dans la prochaine leçon, on entre enfin dans la logique du script : les structures de contrôle, if, switch et les boucles.

5.2 : Bonnes pratiques d’écriture : indentation, commentaires et lisibilité