Het is niet een goede gewoonte, maar een vereiste om je script van het juiste commentaar te voorzien. Zo weten jijzelf en ook anderen hoe jouw script in elkaar steekt. Uiteraard weet je dat zelf op het moment dat je het script aan het schrijven bent, maar geheid dat je het over enkele weken of maanden bent vergeten. Dan ben je dankbaar voor het feit dat je ooit de tijd genomen hebt om dit op een degelijke manier te doen.
Een commentaarregel laat je in PowerShell voorafgaan door een #, dus:
# De variabele $Username wordt gevuld met de huidige gebruikersnaam
$Username = Get-Content Env: USERNAME
Als je meer commentaarregels onder elkaar in een blok wilt zetten, kan dat ook. Gebruik hiervoor het zogenaamde comment-block. Deze ziet er als volgt uit:
<#
Hier staat commentaar regel 1
en hier staat regel 2
en dit commentaarblok wordt afgesloten met regel 3
#>
Het mooie van PowerShell is dat je jouw toegevoegde commentaar meteen kunt gebruiken als tekst voor de helpfile van het eigen script. Dit noemen we comment-based help. Deze comments komen dus in het comment-block (tussen <# en #> te staan). Een aantal voorbeelden die je zou kunnen gebruiken:
.SYNOPSIS
een korte beschrijving van het script.
.DESCRIPTION
een gedetailleerdere beschrijving van het script. .PARAMETER <Parameter-Name> Als je parameters gebruikt, dan be noem je ze hier per stuk, daarbij geef je ook de default-waarde
aan.
.EXAMPLE
Voorbeelden die je wilt geven bij gebruik van het script: deze voorbeelden hoef je niet te nummeren.
.NOTES
eventueel aanvullende informatie over het script of de func tie.
.LINK
eventueel een link waar bijvoorbeeld meer info te vinden is.
Als je een en ander op die manier netjes documenteert (van comments voorziet) en je vraagt vervolgens de helpfile van het eigen script op, dan krijg je deze ook keurig te zien.
Zie onderstaand voorbeeld: Get-Help .\loginscript.ps1 -full
(daar mee krijg je alle info te zien!).
<afbeelding van script in bijlage A>
TIP Voor meer informatie over comment-based help geef je binnen PowerShell het commando:
Get-Help About_Comment_Based_Help
Maak een passende comment based helpfile voor je login script uit opdracht 1 van het onder deel "Een logfile maken"