Documentazione e commenti

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

Non esagerare con i commenti. A meno che il vostro codice non sia particolarmente oscuro, non fate precedere ogni linea da un commento — così facendo spezzettate il codice e lo rendete più difficile da leggere. Invece, scrivete un singolo commento a blocchi.

I commenti a blocchi generalmente si applicano ad alcuni o a tutto il codice che li segue, e sono indentati allo stesso livello di quel codice. Ogni linea dovrebbe iniziare con un # e un singolo spazio.

Se il blocco è particolarmente lungo (come nel caso del testo di documentazione) si raccomanda di usare la sintassi del commento di blocco <# ... #>, ma si dovrebbero mettere i caratteri del commento sulle loro proprie righe, e indentare il commento:

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

I commenti sulla stessa linea di una dichiarazione possono distrarre, ma quando non affermano l’ovvio, e in particolare quando si hanno diverse brevi linee di codice che devono essere spiegate, possono essere utili.

Dovrebbero essere separati dalla dichiarazione di codice da almeno due spazi, e idealmente, dovrebbero allinearsi con qualsiasi altro commento in linea nello stesso blocco di codice.

$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’aiuto basato sui commenti dovrebbe essere scritto in un linguaggio semplice.

Non state scrivendo una tesi per il vostro corso di scrittura tecnica al college – state scrivendo qualcosa che descrive come funziona una funzione. Evitate parole inutilmente grandi e mantenete le vostre spiegazioni brevi. Non state cercando di impressionare nessuno, e le uniche persone che leggeranno questo testo stanno solo cercando di capire come usare la funzione.

Se state scrivendo in quella che è, per voi, una lingua straniera, parole più semplici e strutture di frase più semplici sono migliori, e hanno più probabilità di avere senso per un lettore nativo.

Siate completi, ma concisi.

Posizione

Per assicurare che la documentazione rimanga con la funzione, i commenti alla documentazione dovrebbero essere collocati ALL’INTERNO della funzione, piuttosto che sopra. Per rendere più difficile dimenticare di aggiornarli quando si cambia una funzione, si dovrebbe tenerli all’inizio della funzione, piuttosto che alla fine.

Naturalmente, questo non vuol dire che metterli altrove sia sbagliato — ma questo è più facile da fare, e più difficile da dimenticare di aggiornare.

Metti i dettagli nelle note

Se vuoi fornire spiegazioni dettagliate su come funziona il tuo strumento, usa la sezione Notes per questo.

Descrivi la funzione

Ogni comando di funzione dello script dovrebbe avere almeno una breve dichiarazione che ne descrive la funzione. Questo è il Synopsis.

Documentare ogni parametro

Ogni parametro dovrebbe essere documentato. Per rendere più facile mantenere i commenti sincronizzati con le modifiche ai parametri, la posizione preferita per i commenti di documentazione dei parametri è all’interno del blocco param, direttamente sopra ogni parametro. Esempi possono essere trovati negli snippet ISE:

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

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

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