Documentation et commentaires

Les commentaires qui contredisent le code sont pires que l’absence de commentaires. Faites toujours une priorité de la mise à jour des commentaires lorsque le code change !

Les commentaires doivent être en anglais, et doivent être des phrases complètes. Si le commentaire est court, le point à la fin peut être omis.

Rappellez-vous que les commentaires doivent servir à votre raisonnement et à votre prise de décision, et non pas tenter d’expliquer ce que fait une commande. À l’exception des expressions régulières, un PowerShell bien écrit peut être assez explicite.

# Do not write:
# Increment Margin by 2
$Margin = $Margin + 2
# Maybe write:
# The rendering box obscures a couple of pixels.
$Margin = $Margin + 2

N’abusez pas des commentaires. À moins que votre code ne soit particulièrement obscur, ne faites pas précéder chaque ligne d’un commentaire — ce faisant, vous brisez le code et le rendez plus difficile à lire. Au lieu de cela, écrivez un seul commentaire de bloc.

Les commentaires de bloc s’appliquent généralement à tout ou partie du code qui les suit, et sont indentés au même niveau que ce code. Chaque ligne doit commencer par un # et un espace unique.

Si le bloc est particulièrement long (comme dans le cas d’un texte de documentation), il est recommandé d’utiliser la syntaxe de commentaire de bloc <# ... #>, mais vous devez placer les caractères de commentaire sur leurs propres lignes, et indenter le commentaire :

# Requiring a space makes things legible and prevents confusion.
# Writing comments one-per line makes them stand out more in the console.
<#
 .SYNOPSIS
 Really long comment blocks are tedious to keep commented in single-line mode.
 .DESCRIPTION
 Particularly when the comment must be frequently edited,
 as with the help and documentation for a function or script.
#>

Les commentaires sur la même ligne qu’une déclaration peuvent être distrayants, mais lorsqu’ils n’énoncent pas l’évidence, et en particulier lorsque vous avez plusieurs courtes lignes de code qui nécessitent une explication, ils peuvent être utiles.

Ils doivent être séparés de l’énoncé du code par au moins deux espaces, et idéalement, ils doivent s’aligner avec tout autre commentaire en ligne dans le même bloc de code.

$Options = @{
 Margin = 2 # The rendering box obscures a couple of pixels.
 Padding = 2 # We need space between the border and the text.
 FontSize = 24 # Keep this above 16 so it's readable in presentations.
}

L’aide basée sur les commentaires doit être rédigée dans un langage simple.

Vous n’écrivez pas une thèse pour votre cours de rédaction technique au collège – vous écrivez quelque chose qui décrit le fonctionnement d’une fonction. Évitez les mots inutilement grands, et gardez vos explications courtes. Vous n’essayez pas d’impressionner qui que ce soit, et les seules personnes qui liront ce texte essaieront simplement de comprendre comment utiliser la fonction.

Si vous écrivez dans ce qui est, pour vous, une langue étrangère, des mots plus simples et des structures de phrases plus simples sont préférables, et plus susceptibles d’avoir du sens pour un lecteur natif.

Soyez complet, mais soyez concis.

L’emplacement

Afin de garantir que la documentation reste avec la fonction, les commentaires de documentation doivent être placés DANS la fonction, plutôt qu’au-dessus. Pour qu’il soit plus difficile d’oublier de les mettre à jour lors de la modification d’une fonction, vous devriez les garder en haut de la fonction, plutôt qu’en bas.

Bien sûr, cela ne veut pas dire que les mettre ailleurs est mauvais — mais c’est plus facile à faire, et plus difficile d’oublier de les mettre à jour.

Mettre les détails dans les notes

Si vous voulez fournir des explications détaillées sur le fonctionnement de votre outil, utilisez la section Notes pour cela.

Décrire la fonction

Chaque commande de fonction de script devrait avoir au moins une courte déclaration décrivant sa fonction. C’est la Synopsis.

Documenter chaque paramètre

Chaque paramètre doit être documenté. Pour faciliter la synchronisation des commentaires avec les modifications apportées aux paramètres, l’emplacement préféré pour les commentaires de documentation des paramètres se trouve dans le bloc param, directement au-dessus de chaque paramètre. Des exemples peuvent être trouvés dans les extraits ISE :

param (
 # Param1 help description
 
 $Param1,
 # Param2 help description
 
 $Param2
)

Il est également possible d’écrire des déclarations .PARAMETER avec le reste des commentaires de documentation, mais l’expérience montre qu’ils sont plus susceptibles d’être maintenus à jour si vous les placez plus près du code qu’ils documentent.

Fournir des exemples d’utilisation

Votre aide devrait toujours fournir un exemple pour chaque cas d’utilisation majeur. Un  » exemple d’utilisation  » est juste un exemple de ce que vous taperiez dans Powershell pour exécuter le script – vous pouvez même en couper et coller un depuis la ligne de commande pendant que vous testez votre fonction.

function Test-Help {
 <#
 .SYNOPSIS
 An example function to display how help should be written.
 .EXAMPLE
 Get-Help -Name Test-Help
 This shows the help for the example function.
 #>
 
 param (
 # This parameter doesn't do anything.
 # Aliases: MP
 
 
 $MandatoryParameter
 )
 <# code here ... #>
}

DOC-01 Rédiger une aide sous forme de commentaires

Vous devez toujours rédiger une aide sous forme de commentaires dans vos scripts et fonctions.

L’aide sous forme de commentaires est formatée comme suit :

function Get-Example {
 <#
 .SYNOPSIS
 A brief description of the function or script.
 .DESCRIPTION
 A longer description.
 .PARAMETER FirstParameter
 Description of each of the parameters.
 Note:
 To make it easier to keep the comments synchronized with changes to the parameters,
 the preferred location for parameter documentation comments is not here,
 but within the param block, directly above each parameter.
 .PARAMETER SecondParameter
 Description of each of the parameters.
 .INPUTS
 Description of objects that can be piped to the script.
 .OUTPUTS
 Description of objects that are output by the script.
 .EXAMPLE
 Example of how to run the script.
 .LINK
 Links to further documentation.
 .NOTES
 Detail on what the script does, if this is needed.
 #>

.