Documentação e Comentários

Comentários que contradizem o código são piores do que a ausência de comentários. Manter sempre os comentários actualizados quando o código muda!

Os comentários devem ser em inglês, e devem ser frases completas. Se o comentário for curto, o período no final pode ser omitido.

Lembra-te que os comentários devem servir para o teu raciocínio e tomada de decisão, e não para tentar explicar o que um comando faz. Com excepção de expressões regulares, PowerShell bem escrito pode ser bastante auto-explicativo.

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

Não exagere com comentários. A menos que o seu código seja particularmente obscuro, não preceda cada linha com um comentário — fazendo-o quebra o código e torna mais difícil a sua leitura. Em vez disso, escreva um único bloco de comentários.

Bloquear comentários aplica-se geralmente a algum ou a todo o código que os segue, e são recuados ao mesmo nível que esse código. Cada linha deve começar com um # e um único espaço.

Se o bloco for particularmente longo (como no caso do texto da documentação) recomenda-se a utilização do <# ... #> sintaxe do comentário do bloco, mas deve colocar os caracteres do comentário nas suas próprias linhas, e recuar o comentário:

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

Os comentários na mesma linha de uma declaração podem ser distractores, mas quando não afirmam o óbvio, e particularmente quando tem várias linhas curtas de código que precisam de ser explicadas, podem ser úteis.

Devem ser separados da declaração de código por pelo menos dois espaços, e idealmente, devem alinhar-se com quaisquer outros comentários em linha no mesmo bloco de código.

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

Ajuda baseada em comentários deve ser escrita numa linguagem simples.

Você não está a escrever uma tese para a sua turma universitária de Escrita Técnica – você está a escrever algo que descreve como funciona uma função. Evite palavras desnecessariamente grandes, e mantenha as suas explicações curtas. Não está a tentar impressionar ninguém, e as únicas pessoas que alguma vez irão ler isto estão apenas a tentar descobrir como usar a função.

Se está a escrever numa língua que é, para si, uma língua estrangeira, palavras mais simples e estruturas de frases mais simples são melhores, e mais susceptíveis de fazer sentido para um leitor nativo.

Seja completo, mas seja conciso.

Localização

A fim de assegurar que a documentação permaneça com a função, os comentários da documentação devem ser colocados INTERIORES da função, em vez de acima. Para que seja mais difícil esquecer de os actualizar ao alterar uma função, deve mantê-los no topo da função, em vez de no fundo.

Obviamente, isto não quer dizer que colocá-los noutro lugar é errado — mas isto é mais fácil de fazer, e mais difícil de esquecer de os actualizar.

Coloque Detalhes nas Notas

Se quiser fornecer explicações detalhadas sobre como funciona a sua ferramenta, use a secção Notes para isso.

Descreva a Função

Todos os comandos de funções de script devem ter pelo menos uma breve declaração descrevendo a sua função. Isto é o Synopsis.

Documentar cada parâmetro

Cada parâmetro deve ser documentado. Para facilitar a sincronização dos comentários com as alterações dos parâmetros, o local preferido para comentários de documentação dos parâmetros é dentro do bloco param, directamente acima de cada parâmetro. Exemplos podem ser encontrados nos trechos do ISE:

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

Também é possível escrever .PARAMETER declarações com o resto dos comentários de documentação, mas a experiência mostra que é mais provável que sejam mantidos actualizados se os colocarmos mais perto do código que documentam.

Forneça exemplos de utilização

A sua ajuda deve sempre fornecer um exemplo para cada caso de utilização principal. Um ‘exemplo de utilização’ é apenas um exemplo do que escreveria no Powershell para executar o script – pode até cortar e colar um da linha de comando enquanto está a testar a sua função.

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 Escreva ajuda baseada em comentários

Deve sempre escrever ajuda baseada em comentários nos seus scripts e funções.

Ajuda baseada em comentários é formatada da seguinte forma:

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