Lorsqu’un nouveau venu à PowerShell commence à écrire des scripts, il se concentre généralement sur le code. Après tout, c’est le code qui fait bouger les choses ! Le code exécutable est évidemment important, mais que se passe-t-il lorsque vous écrivez tellement de code que vous oubliez ce qu’il fait ? C’est là que les commentaires PowerShell peuvent intervenir.

Si vous faites partie d’une équipe, comprend-elle le code que vous écrivez ? Les commentaires PowerShell peuvent vous aider.

Écrire des commentaires PowerShell descriptifs et informatifs dans les scripts nous aide, nous les humains, à comprendre l’intention du code, le résultat et peut-être à décrire les cas limites rencontrés à un moment donné.

Dans cet article, vous allez découvrir les différents types de commentaires dans PowerShell, lesquels utiliser et comment les utiliser efficacement dans vos scripts.

Avez-vous déjà écrit du code et dû le réviser des semaines ou des mois plus tard ? Probablement. L’avez-vous compris aussi tard ? Peut-être pas. Si seulement vous aviez laissé des commentaires utiles dans votre code !

La plupart des langages de programmation ont un concept de commentaire. PowerShell ne fait pas exception à la règle. Dans PowerShell, votre ami est #. Tout ce qui suit le hashtag (#) dans la même ligne est ignoré par PowerShell en tant que code interprété.

L’exemple de code ci-dessous est un extrait d’un script qui… eh bien, vous pouvez vous référer au commentaire du script PowerShell sur la première ligne pour savoir ce qu’il fait. Si vous êtes un expert de PowerShell, vous pouvez probablement indiquer ce que fait cet extrait sans le commentaire.

# Get all files with TXT extension, show the name of each file and then delete them.Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName}

Mais, qu’en est-il lorsque vous rencontrez une commande laconique comme celle-ci ci-dessous ?

"{0},{1}" -f (gm -input (1..20) -name count), (1..20).count

Ajouter des commentaires vous rendra, à vous ou à toute personne qui finira par lire votre code, un grand service. Comme vous pouvez le voir ci-dessous, l’ajout d’un commentaire au-dessus de la commande terse fait une grande différence dans la compréhension du code.

#Check whether the object has a property named "count". Then, return true or false."{0},{1}" -f (gm -input (1..20) -name count), (1..20).count

Dans la section précédente, vous avez appris qu’un commentaire commence par un caractère #. Rien ne vous empêche de créer plusieurs lignes de commentaires. En fait, avant PowerShell 2.0, la seule façon de créer des commentaires multilignes est de créer plusieurs lignes de commentaires à une seule ligne.

Il est bon de garder les commentaires brefs et concis, mais certains scénarios nécessitent l’utilisation d’un commentaire multiligne PowerShell, qui peut également être appelé bloc de commentaires PowerShell.

Un bloc de commentaires dans PowerShell commence par <# et se termine par #>. Voici quelques exemples de cas où un bloc de commentaires est applicable.

Séparer un long commentaire en plusieurs lignes

Il est parfois inévitable d’avoir un long commentaire dans un script. Ces longs commentaires peuvent aller bien au-delà de votre cadre actuel d’affichage. Lorsque cela se produit, vous devrez continuer à défiler horizontalement pour lire toute la ligne de commentaire.

Par exemple, au lieu d’avoir un long commentaire d’une seule ligne comme:

# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display. And when that happens, you will need to keep on scrolling horizontally to read the entire comment line.

Pourquoi ne pas le transformer en un commentaire multiligne plus facile à lire comme celui-ci ci-dessous :

<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>

Ajouter du texte descriptif

Vous avez déjà téléchargé ou écrit un script, l’avez enregistré sous un nom aléatoire ou non descriptif ? Je sais que je l’ai fait !

Lorsque vous ouvrez le script pour savoir ce que c’est, ce serait certainement bien s’il y avait des détails utiles listés à l’intérieur comme à quoi sert le script comme qui l’a créé et quand il a été créé.

Un commentaire de bloc dans PowerShell est utile pour ajouter du texte descriptif dans vos scripts. De cette façon, le but du script est déjà donné et c’est également un excellent moyen d’inclure des avertissements ou des choses à surveiller lors de l’utilisation du script.

Vous trouverez ci-dessous un exemple de commentaire de bloc décrivant ce qu’est le script, quand il a été mis à jour pour la dernière fois et montrant également un avertissement de ce qu’il ne faut pas faire lors de l’exécution du script.

<# Using this script will export the email addresses of all mailboxes in the Exchange organization.WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL.Last update: Feb 16, 2020#>

Documenter les exigences et les étapes

Si votre script a une façon spécifique de s’exécuter, ou a des exigences particulières pour s’exécuter, les commentaires de bloc aideraient à le documenter à l’intérieur de votre script ou fonction.

Vous trouverez ci-dessous un exemple de documentation d’une exigence et d’étapes à l’aide de commentaires de bloc.

<#This function requires an encrypted credential XML file that will be usedto authenticate with Office 365.If you don't have this yet, follow these steps.1. Open PowerShell2. Run this command - 'Get-Credential | Export-CliXml .\credential.XML'3. Make sure to save the XML file inside the same folder as the script.NOTE: The credential XML file will only work on the same computer and the same accountused to generate it.#>

Mise en commentaire du code existant

Les commentaires ne servent pas uniquement à ajouter des commentaires. Vous pouvez également transformer des lignes de code existantes en commentaires d’une seule ligne ou en blocs.

Parfois, vous vous retrouvez à tester ou déboguer des scripts. Lorsque le code est commenté, PowerShell évite que ce code ne s’exécute pendant l’exécution.

Par exemple, vous avez un script qui obtient une liste d’utilisateurs dans Active Directory, et cette liste est traitée à l’aide de la boucle foreach pour définir le nom du département de chaque utilisateur à l’aide du Set-AdUser cmdlet.

<#This script will get all AD users matching the filterand each user's department name will be changed to 'Finance'.#>$adUsers = Get-ADUser -Filter *foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}

Mais si vous voulez tester la boucle foreach sans exécuter encore la ligne Set-AdUser, il vous suffit de commenter cette ligne particulière comme suit :

foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" #Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}

Maintenant, le script peut être testé en toute sécurité sans modifier réellement le nom du département de chaque utilisateur.

TIP : Dans Visual Studio Code, vous pouvez commenter une ligne ou plusieurs lignes en appuyant sur le raccourci clavier « CTRL + / ».

Maintenant, si vous voulez commenter plusieurs lignes, vous avez le choix entre mettre un # au début de chaque ligne, ou vous pouvez enfermer plusieurs lignes à l’intérieur du bloc <# #> comme dans l’exemple ci-dessous. Comme vous pouvez le voir, la totalité de la boucle foreach a été transformée en un bloc de commentaires.

$adUsers = Get-ADUser -Filter *<# foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'} #>

TIP : Dans Visual Studio Code, vous pouvez également créer un bloc de commentaires en mettant en surbrillance une ou plusieurs lignes de code et en appuyant sur le raccourci clavier « ALT +SHIFT + A ».

L’aide basée sur les commentaires-.Based Help

Lorsque vous voulez que vos scripts ou fonctions aient l’air plus professionnels, vous pouvez le faire en ajoutant une aide basée sur des commentaires. Une aide basée sur des commentaires est un ensemble de mots-clés et de textes enfermés dans un commentaire de bloc.

Visitez la page – À propos de l’aide basée sur des commentaires – pour en savoir plus sur le mot-clé et la syntaxe de l’aide basée sur des commentaires.

L’exemple de code ci-dessous démontre un script nommé Get-WhatTimeIsItNow.ps1, ayant une aide basée sur les commentaires incluse.

<#.SYNOPSISShort description of the script.DESCRIPTIONLong description of the script.EXAMPLEPS C:\> Get-WhatTimeIsItNow.ps1Explanation of what the example does.INPUTSInputs (if any).OUTPUTSOutput (if any).NOTESGeneral notes#>Get-Date -Format t

L’aide basée sur les commentaires active le support Get-Help pour vos scripts. Cela signifie que lorsque vous exécutez Get-Help <script/function>, PowerShell retournera le texte d »aide’ contenu dans votre script comme celui présenté ci-dessous.

TIP : Dans Visual Studio Code, vous pouvez insérer un bloc d’aide par défaut basé sur les commentaires en tapant comment-help dans le volet de l’éditeur.

.dans Visual Studio Code

Bonnes pratiques

Voici ce que vous pouvez appeler les meilleures pratiques pour créer des commentaires efficaces. Il ne s’agit en aucun cas d’exigences strictes, mais de recommandations que beaucoup mettent déjà en pratique et que vous pouvez utiliser comme guide.

Lorsque vous écrivez du code, vous pourriez être tenté d’ajouter une référence à un numéro de ligne dans vos commentaires. Vous avez peut-être raison de penser que l’ajout de références à un numéro de ligne rend votre code d’autant plus facile à comprendre. Enfin, si vous êtes sûr que votre code ne sera jamais modifié.

Imaginez qu’une nouvelle ligne de code soit insérée dans votre script. Cela signifierait que toutes les références de numéro de ligne dans vos commentaires ont déjà été décalées. Et pour que la numérotation des lignes reste précise, vous devrez modifier les commentaires pour les mettre à jour un par un.

Nous, humains, avons l’habitude de lire de haut en bas. Si le commentaire que vous ajoutez est important pour les lignes de codes qui suivent, il est logique d’ajouter les commentaires avant.

Après tout, si vous ajoutez des commentaires dans le script à propos du script, n’est-il pas plus judicieux de placer les commentaires avant le code et non après ?

Comme dans l’exemple précédent, mettre des commentaires après le code, même s’il est sur la même ligne, n’est pas mieux que de placer le commentaire sous le code.

Ajouter des commentaires à la fin du code peut provoquer des erreurs d’édition car au lieu d’être concentré sur la modification du code, il faudrait aussi penser que le commentaire se déplace au fur et à mesure que le code change.

Ne pas énoncer l’évidence

Parfois, le code est juste trop simple et l’intention est déjà trop évidente pour qu’y ajouter un commentaire soit juste un gaspillage. Généralement, dans cette situation, un commentaire pourrait être encore plus long que le code auquel il fait référence.

Si vous pensez que le code est explicite, vous pouvez envisager de ne pas ajouter de commentaire.

Résumé

Dans cet article, vous avez appris l’importance d’ajouter des commentaires à vos scripts ou fonctions PowerShell. Vous avez également appris les différents types de commentaires disponibles et comment un commentaire correctement rédigé et placé peut augmenter considérablement la lisibilité de votre code.

Il n’y a pas de règles strictes et rapides sur la façon d’appliquer les commentaires dans PowerShell, mais il existe des recommandations testées et éprouvées sur la façon de les utiliser. Au final, c’est à vous de voir comment vous voulez utiliser les commentaires dans vos scripts pour vous rappeler les choses cruciales du début à la fin.

Lecture complémentaire

.