Commenter son code : comment et pourquoi ?
Sommaire
I. Présentation
Que ce soit avec PowerShell ou un autre langage, les commentaires sont une bonne pratique. Un commentaire représente une portion de texte inclus dans votre code et qui ne sera pas exécuté lors de l'exécution du script PowerShell. Les commentaires sont là pour documenter le code et expliquer l'intérêt d'une ligne ou de plusieurs lignes, dans le but d'expliquer le fonctionnement du code.
II. Pourquoi commenter son code ?
Nous pouvons mettre en avant plusieurs arguments pour vous inciter à commenter votre code PowerShell.
- Compréhension : les commentaires aident à comprendre ce que fait le code, ce qui sera particulièrement utile si le code est complexe ou qu'il contient un grand nombre de lignes. Ils peuvent expliquer l'intérêt d'une variable, votre raisonnement ou des détails sur le contexte d'utilisation.
- Maintenance : les commentaires facilitent la maintenance du code. En effet, si vous ou quelqu'un d'autre doit relire ou faire évoluer le code dans plusieurs semaines ou mois, il sera plus facile de comprendre la logique du script et son fonctionnement si le code est bien commenté.
- Travail en équipe : les commentaires sont essentiels lors de la collaboration sur du code avec d'autres personnes, notamment vos collègues. Ils aident les autres à comprendre votre code plus rapidement et plus facilement.
III. Comment commenter son code ?
Maintenant que vous êtes convaincu de l'intérêt de commenter votre code PowerShell, vous devez vous demander comment faire ? En PowerShell, vous pouvez commenter votre code en utilisant le caractère "#". Tout ce qui suit ce caractère sur la même ligne est considéré comme un commentaire.
# Cette commande sert à vérifier si le processus notepad (Bloc-notes) est en cours d'exécution sur la machine
Get-Process -Name "notepad"
# Ceci est un autre commentairePour désactiver temporairement l'exécution d'une ligne, vous n'êtes pas obligé de la supprimer : vous pouvez la commenter temporairement.
Vous pouvez également créer des commentaires multilignes, ou un bloc de commentaires, en utilisant les symboles "<#" et "#>" pour marquer le début et la fin du commentaire.
<# Ceci est un commentaire
qui s'étend sur
plusieurs lignes #>Que ce soit avec Windows PowerShell ISE ou Visual Studio Code, les commentaires sont mis en évidence dans le code grâce à la coloration syntaxique. La couleur verte est associée aux lignes commentées.
IV. L'aide basée sur les commentaires
Dans un script PowerShell, les commentaires peuvent être utilisés pour intégrer une aide au sein même du fichier. En effet, en utilisant la syntaxe précédemment évoquée pour créer un bloc de commentaires, nous allons pouvoir ajouter une aide complète à un script (ou au sein d'une fonction). Ainsi, la commande Get-Help permettra de consulter cette aide qu'elle sera capable d'interpréter.
La syntaxe est la suivante :
<#
.<Mot clé>
<Contenu de l'aide>
#>
# Code PowerShellNous pouvons voir qu'il y a deux informations à indiquer : le mot clé précédé par un point, et le texte associé à ce mot clé, c'est-à-dire à cette section de l'aide. Voici les principaux mots que vous pouvez utiliser :
| Mot clé | Description |
|---|---|
| .SYNOPSIS | Courte description du script ou de la fonction |
| .DESCRIPTION | Longue description / description détaillée du script ou de la fonction |
| .PARAMETER | Description de chaque paramètre du script ou de la fonction |
| .EXAMPLE | Un ou plusieurs d’exemples d’utilisation de la fonction ou du script. Peut-être accompagné avec un exemple de sortie et un commentaire |
| .INPUTS | Types d’objets .NET acceptés en entrée par ce script ou cette fonction |
| .OUTPUTS | Types d’objets .NET retournés en sortie par ce script ou cette fonction |
| .NOTES | Informations supplémentaires telles que l’auteur, le site web de l’auteur, la date de création, l’historique des versions, etc. |
Dans un script nommé "demo.ps1", nous allons ajouter les lignes ci-dessous pour créer la section d'aide "SYNOPSIS" et lui associer un texte. Ce qui donne :
<#
.SYNOPSIS
Ce script de démonstration explique le fonctionnement de l'aide basée sur les commentaires
#>
# Code PowerShellAprès avoir enregistré le fichier, nous pouvons lire l'aide avec Get-Help :
Get-Help .\demo.ps1Si l'on s'intéresse au résultat retourné, visible ci-dessous, nous pouvons voir que la section "SYNOPSIS" contient le texte de notre aide ! La section "DESCRIPTION" est vide car nous ne l'avons pas renseignée.
Voici un exemple plus complet issu de l'un de mes scripts (que vous pouvez retrouver sur GitHub) :
V. Conclusion
En ajoutant une aide basée sur les commentaires au début de votre script et en intégrant des commentaires au-dessus de vos lignes de code, vous pourrez documenter votre script aisément. Même si cela prend du temps d'ajouter des commentaires, gardez à l'esprit que c'est une aide précieuse, que ce soit pour vous, vos collègues ou la communauté si votre script venait à être partagé.
