Commenter son code powershell avec des tags

Sous Linux, les administrateurs peuvent compter sur plusieurs langages de scripts : Bash, Perl, KSH, … Powershell est une véritable évolution pour les administrateurs Windows. On dispose dorénavant d’un langage de script riche (utilisation du framework .net) et concis (enchainement des commandes avec des pipe). Cette richesse augmente la complexité au code.

Les développeurs vous le diront un code maintenable est un code documenté. En java, il existe la javadoc (documentation en html) qui peut être générée à partir de balises insérés dans le code. Pour les administrateurs systèmes, la documentation consiste à insérer des commentaires au dessus commandes (ex: @REM pour le batch). PowerShell (surtout la v2) permet de normaliser les commentaires.

1. La syntaxe des commentaires

Il existe 2 types de commentaires :

• Commentaire monoligne :  le début de la  ligne doit commencer par le caractère # .
• Commentaire multilignes :  le bloc de commentaires est ouvert par les caractères  <# et refermer par les caractères #> .
2. Entête d’un fichier ps1 ou psm1

Il est important que dés le début d’un fichier, on sache un certain nombre d’infos : traitements réalisés, l’auteur, la date, …. Pour cela, il faut définir un header.  Les balises sont libres. Voici celles recommandées dans les bonnes pratiques PowerShell:


# =======================================================
# NAME: XXXXXX.ps1
# AUTHOR: Nom Prénom, Entreprise
# DATE: DD/MM/YYYY
#
# KEYWORDS: YYY, XXXXXXXXX , AAAAAA
# VERSION 1.X
# DD/MM/YYYY added help to the functions
# COMMENTS: Desription des traitements
#
#Requires -Version 2.0
# =======================================================




3. Commenter les fonctions

<#
.SYNOPSIS
Description brève de la function
.DESCRIPTION
.PARAMETER
.EXAMPLE
Exemple d’appel de la fonction
.INPUTS
.OUTPUTS
.NOTES
NAME:  Nom de la note
AUTHOR: Nom Prénom
LASTEDIT: DD/MM/YYYY
VERSION:1.0.0 Création de la fonction
1.X.X Ajout d’une fonctionnalité
.LINK
http://www.xxxxx.com
file.ps1
#>


Balise	Description
.SYNOPSIS	Brève description commençant par un verbe
.DESCRIPTION	Description sur plusieurs lignes commençant par « La fonction xxxx  » .
.PARAMETER	Description des paramètres. Un balise .Parameter par paramètres.
.EXAMPLE	Exemple d’appel de la fonction avec un exemple de retour. Plusieurs exemples peuvent être cités.
.INPUTS	Description des objets acceptés en entrée. (??)
.OUTPUTS	Description des objets acceptés en sortie. (??)
.NOTES	Commentaires permettant de versionner le fonction.
.LINK	Lien vers des sites Web ou des fichiers

4. Commenter le code

Les commentaires dans le code sont libres. Il faut néanmoins essayer de les cadrer au maximum afin de dépersonnaliser le code dans le but de le rendre maintenable par n’importe qui.

Exemple de balises :
#TODO: Description du/des améliorations à apporter à une partie de code

#INPROGRESS: Description du/des opérations en cours de développement

 

5. Exemple de code

function Test-Port{
<#
 .SYNOPSIS
     Verifie d’un port tcp distant
 .DESCRIPTION
     La fonction TEST-Port retourne $true si le port est ouvert sinon $false
 .PARAMETER Host
        Nom du volume ex: c:
 .PARAMETER Port
        Numéro de port TCP (inférieure  à 65535)
 .PARAMETER Timeout
        Durée du timeout en ms (par défaut 300ms)
 .NOTES
     Author : Romain Bachimont
     Requires : PowerShell V2
 .EXAMPLE
     [ps] c:\foo> Test-Port « 10.17.215.50 »  8080
     true
  #>
param(
[Parameter(Mandatory=$true,Position=0)][String[]]$Host ,
[Parameter(Mandatory=$true,Position=1)][ValidateRange(0,65535)] [Long]$Port,
[Parameter(Mandatory=$false,Position=2)][Long]$Timeout=300
)
$tcpclient = new-Object system.Net.Sockets.TcpClient
$iar = $tcpclient.BeginConnect($Host,$Port,$null,$null)

# Set the wait time
$wait = $iar.AsyncWaitHandle.WaitOne($Timeout,$false)

# Check to see if the connection is done
if(!$wait)
{
# Close the connection and report timeout
$tcpclient.Close()
Return $false
}
else
{
# Close the connection and report the error if there is one
$error.Clear()
$tcpclient.EndConnect($iar) | out-Null
if(!$?){$failed = $true}
$tcpclient.Close()
}

# Return $true if connection Establish else $False
if($failed){return $false}else{return $true}
}

En complément de ce billet, je vous recommande le livre suivant:
http://blogs.msdn.com/b/microsoft_press/archive/2009/12/16/new-book-windows-powershell-2-0-best-practices.aspx
Il vous permettra de partir sur des bases solides et de rendre vos scripts maintenables et évolutifs.