Quando um recém-chegado ao PowerShell começa a escrever scripts, normalmente concentram-se no código. Afinal de contas, o código é o que faz as coisas acontecerem! O código executável é obviamente importante, mas o que acontece quando se escreve tanto código, esquece-se do que ele faz? É aqui que os comentários do PowerShell podem chegar.

Se estás numa equipa, será que eles compreendem o código que estás a escrever? Os comentários PowerShell podem ajudar.

Escrever comentários descritivos e informativos PowerShell em scripts ajuda-nos a nós humanos a compreender a intenção do código, o resultado, e talvez descreve casos extremos que foram encontrados em determinado momento.

Neste artigo, vai aprender sobre os diferentes tipos de comentários em PowerShell, quais os que deve usar e como usá-los eficazmente nos seus scripts.

P>Deixou alguma vez escrever algum código e teve de o rever semanas ou meses mais tarde? Provavelmente. Compreendeu-o assim tanto mais tarde? Talvez não. Se apenas deixasse alguns comentários úteis no seu código!

As principais linguagens de programação têm um conceito de comentário. PowerShell não é excepção. Em PowerShell, o seu amigo é #. Tudo o que segue o hashtag (#) na mesma linha é ignorado pelo PowerShell como código interpretado.

O código de exemplo abaixo é um excerto de um script que… bem, pode consultar o comentário do script PowerShell na primeira linha para saber o que ele faz. Se for um especialista em PowerShell, pode provavelmente apontar o que este trecho faz sem o comentário.

# Get all files with TXT extension, show the name of each file and then delete them.Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName}

Mas, que tal quando encontrar um comando terse como este abaixo?

"{0},{1}" -f (gm -input (1..20) -name count), (1..20).count

Adicionar comentários far-lhe-á a si ou a qualquer pessoa que acabará por ler o seu código um grande serviço. Como pode ver abaixo, adicionar um comentário acima do comando terse faz muita diferença na compreensão do código.

#Check whether the object has a property named "count". Then, return true or false."{0},{1}" -f (gm -input (1..20) -name count), (1..20).count

Na secção anterior, aprendeu que um comentário começa com um carácter #. Não há nada que o impeça de criar múltiplas linhas de comentários. De facto, antes do PowerShell 2.0, a única forma de criar comentários com várias linhas é criar várias linhas de comentários de uma única linha.

É bom manter os comentários breves e concisos, mas alguns cenários exigem a utilização de um comentário multilinha PowerShell, que também pode ser referido como um bloco de comentários PowerShell.

Um bloco de comentários no PowerShell começa com <# e termina com #>. Abaixo estão alguns exemplos de quando um bloco de comentários é aplicável.

Dividir um Comentário Longo em Múltiplas Linhas

É por vezes inevitável ter um comentário longo num script. Estes comentários longos podem ir muito além do seu quadro actual do ecrã. Quando isso acontecer, terá de continuar a rolar horizontalmente para ler toda a linha de comentários.

Por exemplo, em vez de ter um longo comentário de uma linha como:

# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display. And when that happens, you will need to keep on scrolling horizontally to read the entire comment line.

Por que não transformá-lo num comentário de várias linhas que seja mais fácil de ler como este abaixo:

<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>

Adicionar Texto Descritivo

Deixar alguma vez descarregado ou escrito um script, guardado sob algum nome aleatório ou não descritivo? Eu sei que tenho!

Quando abre o script para descobrir o que raio é, seria certamente bom se houvesse detalhes úteis listados no interior como para que serve o script, como para quem o criou e quando foi criado.

Um comentário em bloco no PowerShell é útil para adicionar texto descritivo nos seus scripts. Desta forma, a finalidade do script já é dada e é também uma óptima forma de incluir avisos ou coisas a ter em atenção quando se usa o script.

Below é um exemplo de um comentário de bloco descrevendo o que é o script, quando foi actualizado pela última vez e também mostra um aviso do que não fazer quando se executa o script.

<# Using this script will export the email addresses of all mailboxes in the Exchange organization.WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL.Last update: Feb 16, 2020#>

Documentar requisitos e passos

Se o seu script tem uma forma específica de executar, ou tem requisitos especiais para executar, bloquear comentários ajudaria a documentá-lo dentro do seu script ou função.

Below é um exemplo de documentação de um requisito e passos usando comentários em bloco.

<#This function requires an encrypted credential XML file that will be usedto authenticate with Office 365.If you don't have this yet, follow these steps.1. Open PowerShell2. Run this command - 'Get-Credential | Export-CliXml .\credential.XML'3. Make sure to save the XML file inside the same folder as the script.NOTE: The credential XML file will only work on the same computer and the same accountused to generate it.#>

Comentar Código Existente

Os comentários são usados não apenas com o propósito de adicionar comentários. Pode também transformar as linhas de código existentes em uma única linha ou bloquear comentários.

Talvez se encontre a testar ou a depurar scripts. Quando o código é comentado, o PowerShell salta esse código da execução durante o tempo de execução.

Por exemplo, tem um script que obtém uma lista de utilizadores no Active Directory, e essa lista é processada usando o laço foreach para definir o nome do departamento de cada utilizador usando o Set-AdUser cmdlet.

<#This script will get all AD users matching the filterand each user's department name will be changed to 'Finance'.#>$adUsers = Get-ADUser -Filter *foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}

Mas se quiser testar o laço foreach sem correr a linha Set-AdUser ainda, só precisa de comentar essa linha em particular assim:

foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" #Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}

Agora o script pode ser testado em segurança sem realmente alterar o nome do departamento de cada utilizador.

TIP: No Visual Studio Code, pode comentar uma linha ou múltiplas linhas premindo o atalho de teclado “CTRL + /”.

Now, se quiser comentar várias linhas, pode escolher entre colocar um # no início de cada linha, ou pode incluir várias linhas dentro do <# #> bloco como mostrado no exemplo abaixo. Como pode ver, todo o laço frontal foi transformado num bloco de comentários.

$adUsers = Get-ADUser -Filter *<# foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'} #>

TIP: Em Visual Studio Code, também pode criar um bloco de comentários realçando uma linha ou múltiplas linhas de código e premindo o atalho de teclado “ALT +SHIFT + A”.

Comment-Ajuda Baseada

Quando quiser fazer com que os seus scripts ou funções pareçam mais profissionais, pode fazê-lo adicionando ajuda com base em comentários. Uma ajuda baseada em comentários é uma colecção de palavras-chave e textos incluídos num bloco de comentários.

Visitar a página – Sobre a Ajuda Baseada em Comentários – para saber mais sobre a palavra-chave e sintaxe da Ajuda Baseada em Comentários.

O código de amostra abaixo demonstra um script chamado Get-WhatTimeIsItNow.ps1, tendo uma ajuda baseada em comentários incluída.

<#.SYNOPSISShort description of the script.DESCRIPTIONLong description of the script.EXAMPLEPS C:\> Get-WhatTimeIsItNow.ps1Explanation of what the example does.INPUTSInputs (if any).OUTPUTSOutput (if any).NOTESGeneral notes#>Get-Date -Format t

Autorização baseada em comentários Get-Help suporte para os seus scripts. Isto significa que quando executar Get-Help <script/function>, PowerShell devolverá o texto de ‘ajuda’ contido no seu script como o mostrado abaixo.

TIP: No Visual Studio Code, pode inserir um bloco de ajuda padrão baseado em comentários, digitando no painel de ajuda do editor.

Belas Práticas

Aqui estão algumas do que se pode chamar melhores práticas para criar comentários eficazes. Estes não são de forma alguma requisitos difíceis, mas são recomendações que muitos já colocam em prática que pode utilizar como guia.

Quando escrever código, poderá ser tentado a adicionar uma referência a um número de linha nos seus comentários. Pode estar certo ao pensar que adicionar referências a um número de linha torna o seu código muito mais fácil de compreender. Ou seja, se tiver a certeza de que o seu código nunca será modificado.

Imagine que uma nova linha de código é inserida no seu script. Isto significaria que todas as referências de número de linha nos seus comentários já foram deslocadas. E para manter a numeração de linha precisa, terá de editar os comentários para os actualizar um a um.

Nós, humanos, estamos habituados a ler de cima para baixo. Se o comentário que está a adicionar é importante para as linhas de códigos seguintes, então é apenas lógico adicionar os comentários antes.

Depois de tudo, se está a acrescentar comentários no guião sobre o guião, não será mais sensato ter os comentários antes do código e não depois?

O mesmo que o exemplo anterior, colocar comentários após o código, mesmo que seja na mesma linha, não é melhor do que colocar o comentário abaixo do código.

Adicionar comentários no fim do código pode causar erros de edição porque, em vez de estar concentrado em modificar o código, também teria de ter em mente que o comentário se desloca à medida que o código muda.

Não afirmar o óbvio

Por vezes o código é demasiado simples e a intenção já é demasiado óbvia que acrescentar um comentário a ele é apenas um desperdício. Geralmente nesta situação, um comentário poderia ser ainda mais longo do que o código a que se refere.

Se acredita que o código é auto-explicativo, pode querer considerar saltar a adição de um comentário.

Summary

Neste artigo, aprendeu a importância de adicionar comentários aos seus scripts ou funções PowerShell. Aprendeu também os diferentes tipos de comentários disponíveis e como um comentário devidamente trabalhado e colocado pode aumentar significativamente a legibilidade do seu código.

Não existem regras rígidas e rápidas sobre como aplicar comentários no PowerShell, mas existem recomendações testadas e comprovadas sobre como utilizá-los. No final, cabe-lhe a si como pretende utilizar os comentários nos seus scripts para o lembrar das coisas cruciais do princípio ao fim.

Leitura adicional