Documentatie en commentaar

Commentaar dat in tegenspraak is met de code is erger dan geen commentaar. Maak er altijd een prioriteit van om de commentaren up-to-date te houden wanneer de code verandert.

Commentaren moeten in het Engels zijn, en moeten volledige zinnen zijn. Als het commentaar kort is, kan de punt aan het eind worden weggelaten.

Houd in gedachten dat commentaar moet dienen om uw redenering en besluitvorming te ondersteunen, niet om te proberen uit te leggen wat een commando doet. Met uitzondering van reguliere expressies, kan goed geschreven PowerShell vrij zelfverklarend zijn.

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

Ga niet te ver met commentaar. Tenzij je code bijzonder obscuur is, moet je niet elke regel vooraf laten gaan door commentaar — door dit te doen, wordt de code opgebroken en moeilijker te lezen. Schrijf in plaats daarvan een enkel blokcommentaar.

Blokcommentaar is meestal van toepassing op sommige of alle code die erop volgt, en is ingesprongen op hetzelfde niveau als die code. Elke regel moet beginnen met een # en een enkele spatie.

Als het blok bijzonder lang is (zoals in het geval van documentatietekst) wordt aanbevolen de <# ... #> syntaxis voor blokcommentaar te gebruiken, maar u moet de commentaartekens op hun eigen regels plaatsen, en het commentaar laten inspringen:

# 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.
#>

Commentaren op dezelfde regel als een verklaring kunnen afleiden, maar als ze niet het voor de hand liggende verklaren, en vooral als je een aantal korte regels code hebt die uitleg behoeven, kunnen ze nuttig zijn.

Ze moeten worden gescheiden van de code verklaring door ten minste twee spaties, en idealiter moeten ze op een lijn staan met alle andere inline commentaar in hetzelfde blok van 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.
}

Commentaar-gebaseerde hulp moet in eenvoudige taal worden geschreven.

Je schrijft geen scriptie voor je college Technisch Schrijven – je schrijft iets dat beschrijft hoe een functie werkt. Vermijd onnodig grote woorden, en houd je uitleg kort. Je probeert op niemand indruk te maken, en de enige mensen die dit ooit zullen lezen, proberen alleen maar uit te vinden hoe je de functie moet gebruiken.

Als je schrijft in wat voor jou een vreemde taal is, zijn eenvoudigere woorden en eenvoudigere zinsconstructies beter, en is de kans groter dat een moedertaalspreker er iets aan heeft.

Ben volledig, maar wees beknopt.

Locatie

Om ervoor te zorgen dat de documentatie bij de functie blijft, moet documentatie-commentaar BINNEN de functie worden geplaatst, in plaats van erboven. Om het moeilijker te maken om ze te vergeten bij te werken als je een functie wijzigt, moet je ze bovenaan de functie plaatsen, in plaats van onderaan.

Dat wil natuurlijk niet zeggen dat het verkeerd is om ze ergens anders te plaatsen — maar dit is gemakkelijker om te doen, en moeilijker om te vergeten bij te werken.

Zet details in de Notes

Als je gedetailleerde uitleg wilt geven over hoe je tool werkt, gebruik dan de Notes sectie daarvoor.

Beschrijf de functie

Elk script functie commando zou op zijn minst een korte verklaring moeten hebben die de functie beschrijft. Dat is de Synopsis.

Documenteer elke parameter

Elke parameter moet worden gedocumenteerd. Om het makkelijker te maken het commentaar synchroon te houden met veranderingen in de parameters, is de voorkeurslocatie voor parameterdocumentatie commentaar binnen het param blok, direct boven elke parameter. Voorbeelden zijn te vinden in de ISE snippets:

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

Het is ook mogelijk om .PARAMETER statements te schrijven met de rest van het documentatie commentaar, maar de ervaring leert dat de kans groter is dat ze up-to-date worden gehouden als je ze dichter bij de code zet die ze documenteren.

Gebruiksvoorbeelden

Uw help moet altijd een voorbeeld geven voor elk belangrijk gebruik. Een ‘gebruiksvoorbeeld’ is gewoon een voorbeeld van wat u in Powershell zou typen om het script uit te voeren – u kunt er zelfs een knippen en plakken vanaf de opdrachtregel terwijl u uw functie test.

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 Schrijf hulp op basis van commentaar

Je moet altijd hulp op basis van commentaar schrijven in je scripts en functies.

Hulp op basis van commentaar wordt als volgt geformatteerd:

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.
 #>