Dokumentation und Kommentare

Kommentare, die dem Code widersprechen, sind schlimmer als keine Kommentare. Halten Sie die Kommentare immer auf dem neuesten Stand, wenn sich der Code ändert!

Kommentare sollten in Englisch verfasst sein und aus vollständigen Sätzen bestehen. Wenn der Kommentar kurz ist, kann der Punkt am Ende weggelassen werden.

Erinnern Sie sich daran, dass Kommentare Ihrer Argumentation und Entscheidungsfindung dienen sollten und nicht versuchen zu erklären, was ein Befehl tut. Mit Ausnahme von regulären Ausdrücken kann gut geschriebene PowerShell ziemlich selbsterklärend sein.

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

Übertreiben Sie es nicht mit Kommentaren. Sofern Ihr Code nicht besonders undurchsichtig ist, sollten Sie nicht jeder Zeile einen Kommentar voranstellen – das bricht den Code auf und macht ihn schwieriger zu lesen. Schreiben Sie stattdessen einen einzelnen Blockkommentar.

Blockkommentare beziehen sich im Allgemeinen auf einen Teil oder den gesamten Code, der ihnen folgt, und werden auf der gleichen Ebene wie dieser Code eingerückt. Jede Zeile sollte mit einem # und einem einzelnen Leerzeichen beginnen.

Wenn der Block besonders lang ist (wie im Fall von Dokumentationstext), wird empfohlen, die <# ... #>-Blockkommentar-Syntax zu verwenden, aber Sie sollten die Kommentarzeichen auf ihre eigenen Zeilen setzen und den Kommentar einrücken:

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

Kommentare in der gleichen Zeile wie eine Anweisung können ablenkend wirken, aber wenn sie nicht das Offensichtliche erklären, und besonders wenn Sie mehrere kurze Codezeilen haben, die erklärt werden müssen, können sie nützlich sein.

Sie sollten von der Code-Anweisung durch mindestens zwei Leerzeichen getrennt sein, und idealerweise sollten sie mit anderen Inline-Kommentaren im selben Code-Block in einer Reihe stehen.

$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.
}

Kommentarbasierte Hilfen sollten in einfacher Sprache geschrieben werden.

Sie schreiben keine Diplomarbeit für Ihren Kurs für Technisches Schreiben an der Universität – Sie schreiben etwas, das beschreibt, wie eine Funktion funktioniert. Vermeiden Sie unnötig große Worte, und halten Sie Ihre Erklärungen kurz. Sie versuchen nicht, irgendjemanden zu beeindrucken, und die einzigen Leute, die das lesen werden, versuchen nur herauszufinden, wie man die Funktion benutzt.

Wenn Sie in einer für Sie fremden Sprache schreiben, sind einfachere Wörter und einfachere Satzstrukturen besser, und es ist wahrscheinlicher, dass sie für einen muttersprachlichen Leser Sinn ergeben.

Sein Sie vollständig, aber seien Sie prägnant.

Ort

Um sicherzustellen, dass die Dokumentation bei der Funktion bleibt, sollten Dokumentationskommentare INNERHALB der Funktion platziert werden, anstatt darüber. Um es schwerer zu machen, zu vergessen, sie zu aktualisieren, wenn eine Funktion geändert wird, sollten Sie sie am Anfang der Funktion platzieren, statt am Ende.

Das heißt natürlich nicht, dass es falsch ist, sie an anderer Stelle zu platzieren – aber das ist einfacher zu tun und schwerer zu vergessen, sie zu aktualisieren.

Details in die Notizen schreiben

Wenn Sie detaillierte Erklärungen zur Funktionsweise Ihres Werkzeugs geben wollen, verwenden Sie dafür den Notes-Abschnitt.

Beschreiben Sie die Funktion

Jeder Skript-Funktionsbefehl sollte zumindest eine kurze Aussage haben, die seine Funktion beschreibt. Das ist der Synopsis.

Dokumentieren Sie jeden Parameter

Jeder Parameter sollte dokumentiert werden. Um es einfacher zu machen, die Kommentare mit Änderungen an den Parametern synchron zu halten, ist der bevorzugte Ort für Kommentare zur Parameterdokumentation innerhalb des param-Blocks, direkt über jedem Parameter. Beispiele finden Sie in den ISE-Snippets:

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

Es ist auch möglich, .PARAMETER-Anweisungen mit dem Rest der Dokumentationskommentare zu schreiben, aber die Erfahrung zeigt, dass sie eher auf dem neuesten Stand gehalten werden, wenn Sie sie näher am Code platzieren, den sie dokumentieren.

Bereitstellen von Anwendungsbeispielen

Ihre Hilfe sollte immer ein Beispiel für jeden wichtigen Anwendungsfall bereitstellen. Ein „Verwendungsbeispiel“ ist nur ein Beispiel dafür, was Sie in die Powershell eingeben würden, um das Skript auszuführen – Sie können sogar eines aus der Befehlszeile ausschneiden und einfügen, während Sie Ihre Funktion testen.

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 Schreiben Sie kommentarbasierte Hilfe

Sie sollten immer kommentarbasierte Hilfe in Ihre Skripte und Funktionen schreiben.

Kommentarbasierte Hilfe ist wie folgt formatiert:

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