Dokumentacja i komentarze

Komentarze, które są sprzeczne z kodem są gorsze niż brak komentarzy. Zawsze dbaj o to, aby komentarze były aktualne, gdy kod się zmienia!

Komentarze powinny być w języku angielskim i powinny być pełnymi zdaniami. Jeśli komentarz jest krótki, kropka na końcu może być pominięta.

Pamiętaj, że komentarze powinny służyć Twojemu rozumowaniu i podejmowaniu decyzji, a nie próbować wyjaśniać, co dana komenda robi. Z wyjątkiem wyrażeń regularnych, dobrze napisany PowerShell może być całkiem zrozumiały.

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

Nie przesadzaj z komentarzami. O ile twój kod nie jest szczególnie niejasny, nie poprzedzaj każdej linii komentarzem – takie postępowanie rozbija kod i utrudnia jego czytanie. Zamiast tego, napisz pojedynczy komentarz blokowy.

Komentarze blokowe zazwyczaj odnoszą się do części lub całości kodu, który po nich następuje, i są wcięte do tego samego poziomu, co ten kod. Każda linia powinna zaczynać się od znaku # i pojedynczej spacji.

Jeżeli blok jest szczególnie długi (jak w przypadku tekstu dokumentacji), zaleca się użycie składni komentarza blokowego <# ... #>, ale należy umieścić znaki komentarza w ich własnych liniach, oraz wcięcie komentarza:

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

Komentarze w tej samej linii co wypowiedź mogą być rozpraszające, ale gdy nie stwierdzają oczywistości, a szczególnie gdy masz kilka krótkich linii kodu, które wymagają wyjaśnienia, mogą być przydatne.

Powinny być oddzielone od kodu co najmniej dwiema spacjami, a najlepiej, aby znajdowały się w jednej linii z innymi komentarzami inline w tym samym bloku kodu.

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

Pomoc oparta na komentarzach powinna być napisana prostym językiem.

Nie piszesz pracy dyplomowej na zajęcia z Technical Writing w college’u – piszesz coś, co opisuje działanie funkcji. Unikaj niepotrzebnie dużych słów, a wyjaśnienia powinny być krótkie. Nie próbujesz nikomu zaimponować, a jedynymi osobami, które będą to czytać, są osoby próbujące dowiedzieć się, jak używać danej funkcji.

Jeśli piszesz w języku obcym, prostsze słowa i prostsze struktury zdań są lepsze i bardziej prawdopodobne, że będą miały sens dla rodzimego czytelnika.

Bądź kompletny, ale zwięzły.

Położenie

Aby zapewnić, że dokumentacja pozostanie z funkcją, komentarze do dokumentacji powinny być umieszczone Wewnątrz funkcji, a nie nad nią. Aby trudniej było zapomnieć o ich aktualizacji podczas zmiany funkcji, powinieneś trzymać je na górze funkcji, a nie na dole.

Oczywiście, to nie znaczy, że umieszczenie ich w innym miejscu jest złe — ale jest to łatwiejsze do zrobienia i trudniej zapomnieć o aktualizacji.

Szczegóły w notatkach

Jeśli chcesz dostarczyć szczegółowych wyjaśnień na temat działania twojego narzędzia, użyj do tego sekcji Notes

Opis funkcji

Każde polecenie funkcji skryptu powinno mieć przynajmniej krótką informację opisującą jego funkcję. To jest właśnie Synopsis.

Dokumentuj każdy parametr

Każdy parametr powinien być udokumentowany. Aby ułatwić synchronizację komentarzy ze zmianami parametrów, preferowanym miejscem dla komentarzy dokumentujących parametry jest blok param, bezpośrednio nad każdym parametrem. Przykłady można znaleźć w snippetach ISE:

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

Możliwe jest również pisanie .PARAMETER oświadczeń z resztą komentarzy do dokumentacji, ale doświadczenie pokazuje, że są one bardziej prawdopodobne, że będą aktualizowane, jeśli umieścisz je bliżej kodu, który dokumentują.

Dostarczaj przykłady użycia

Twoja pomoc powinna zawsze dostarczać przykładów dla każdego głównego przypadku użycia. Przykład użycia” to po prostu przykład tego, co wpisałbyś do Powershell, aby uruchomić skrypt – możesz nawet wyciąć i wkleić go z wiersza poleceń podczas testowania funkcji.

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 Pisz pomoc opartą na komentarzach

W skryptach i funkcjach zawsze należy pisać pomoc opartą na komentarzach.

Pomoc oparta na komentarzach jest sformatowana w następujący sposób:

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