Quando un nuovo arrivato in PowerShell inizia a scrivere script, tipicamente si concentra sul codice. Dopo tutto, il codice è ciò che fa accadere le cose! Il codice eseguibile è ovviamente importante, ma cosa succede quando si scrive così tanto codice da dimenticare cosa fa? Questo è quando i commenti PowerShell possono entrare in gioco.

Se sei in una squadra, capiscono il codice che stai scrivendo? I commenti PowerShell possono aiutare.

Scrivere commenti PowerShell descrittivi e informativi negli script aiuta noi umani a capire l’intenzione del codice, il risultato, e forse descrive i casi limite che sono stati incontrati una volta.

In questo articolo, imparerai i diversi tipi di commenti in PowerShell, quali usare e come usarli efficacemente nei tuoi script.

Ti è mai capitato di scrivere del codice e di doverlo rivedere settimane o mesi dopo? Probabilmente. L’avete capito così tanto dopo? Forse no. Se solo avessi lasciato dei commenti utili nel tuo codice!

La maggior parte dei linguaggi di programmazione hanno un concetto di commento. PowerShell non fa eccezione. In PowerShell, il tuo amico è #. Tutto ciò che segue l’hashtag (#) nella stessa linea viene ignorato da PowerShell come codice interpretato.

Il codice di esempio qui sotto è un estratto da uno script che… beh, potete fare riferimento al commento dello script PowerShell sulla prima linea per sapere cosa fa. Se sei un esperto di PowerShell, probabilmente puoi indicare cosa fa questo snippet senza il commento.

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

Ma, che dire di quando incontri un comando terso come questo qui sotto?

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

L’aggiunta di commenti farà un grande servizio a te o a chiunque leggerà il tuo codice. Come potete vedere qui sotto, aggiungere un commento sopra il comando terse fa molta differenza nella comprensione del codice.

#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

Nella sezione precedente, avete imparato che un commento inizia con un carattere #. Non c’è niente che ti impedisca di creare più righe di commenti. Infatti, prima di PowerShell 2.0, l’unico modo per creare commenti multilinea è quello di creare più righe di commenti a linea singola.

È bene mantenere i commenti brevi e concisi, ma alcuni scenari richiedono l’uso di un commento multilinea in PowerShell, che può anche essere chiamato blocco di commento in PowerShell.

Un blocco di commento in PowerShell inizia con <# e finisce con #>. Sotto ci sono alcuni esempi di quando un blocco di commento è applicabile.

Dividere un lungo commento in più righe

A volte è inevitabile avere un lungo commento in uno script. Questi lunghi commenti possono andare ben oltre il frame corrente della visualizzazione. Quando ciò accade, è necessario continuare a scorrere orizzontalmente per leggere l’intera riga del commento.

Per esempio, invece di avere un lungo commento a linea singola come:

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

Perché non trasformarlo in un commento multilinea più facile da leggere come questo qui sotto:

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

Aggiungere testo descrittivo

Hai mai scaricato o scritto uno script, salvato con un nome casuale o non descrittivo? Io so di averlo fatto!

Quando apri lo script per scoprire cosa diavolo è, sarebbe sicuramente bello se ci fossero dei dettagli utili elencati all’interno, come ad esempio a cosa serve lo script, chi lo ha creato e quando è stato creato.

Un commento a blocchi in PowerShell è utile per aggiungere del testo descrittivo nei tuoi script. In questo modo, lo scopo dello script è già dato ed è anche un ottimo modo per includere avvertimenti o cose a cui fare attenzione quando si usa lo script.

Di seguito è riportato un esempio di commento a blocchi che descrive cos’è lo script, quando è stato aggiornato l’ultima volta e mostra anche un avvertimento su cosa non fare quando si esegue lo 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#>

Documentare i requisiti e i passi

Se il vostro script ha un modo specifico per essere eseguito, o ha requisiti speciali per essere eseguito, i commenti a blocchi vi aiuterebbero a documentarlo all’interno del vostro script o funzione.

Di seguito c’è un esempio di documentazione di un requisito e dei passi usando i commenti a blocchi.

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

Commentare il codice esistente

I commenti sono usati non solo per aggiungere commenti. Puoi anche trasformare linee di codice esistenti in commenti a linea singola o a blocchi.

Per esempio, ti trovi a testare o a fare il debug degli script. Quando il codice viene commentato, PowerShell salta l’esecuzione di quel codice durante il runtime.

Per esempio, avete uno script che ottiene una lista di utenti in Active Directory, e quella lista viene processata usando il ciclo foreach per impostare il nome del dipartimento di ogni utente usando il cmdlet Set-AdUser.

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

Ma se si vuole testare il ciclo foreach senza eseguire ancora la linea Set-AdUser, allora basta commentare quella particolare linea in questo modo:

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

Ora lo script può essere tranquillamente testato senza cambiare effettivamente il nome del dipartimento di ogni utente.

TIP: In Visual Studio Code, è possibile commentare una linea o più linee premendo la scorciatoia da tastiera “CTRL + /”.

Ora, se volete commentare più linee, avete la scelta di mettere un # all’inizio di ogni linea, o potete racchiudere più linee dentro il blocco <# #> come mostrato nell’esempio qui sotto. Come potete vedere, l’intero ciclo foreach è stato trasformato in un blocco di commento.

$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: In Visual Studio Code, potete anche creare un blocco di commento evidenziando una linea o più linee di codice e premendo la scorciatoia da tastiera “ALT +SHIFT + A”.

Comment-Based Help

Quando volete rendere i vostri script o funzioni più professionali, potete renderli tali aggiungendo un aiuto basato sui commenti. Un aiuto basato sui commenti è un insieme di parole chiave e testi racchiusi in un commento di blocco.

Visita la pagina – About Comment Based Help – per saperne di più sulla parola chiave Comment-Based Help e sulla sintassi.

Il codice di esempio qui sotto dimostra uno script chiamato Get-WhatTimeIsItNow.ps1, con un aiuto basato sui commenti incluso.

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

Comment-based permette il supporto Get-Help per i tuoi script. Questo significa che quando si esegue Get-Help <script/function>, PowerShell restituirà il testo di ‘aiuto’ contenuto nel vostro script come quello mostrato di seguito.

TIP: In Visual Studio Code, potete inserire un blocco di aiuto predefinito basato sui commenti digitando comment-help nel pannello dell’editor.

Best Practices

Queste sono alcune di quelle che si possono chiamare best practices per creare commenti efficaci. Questi non sono in alcun modo requisiti rigidi, ma sono raccomandazioni che molti già mettono in pratica e che potete usare come guida.

Quando scrivete codice, potreste essere tentati di aggiungere un riferimento ad un numero di linea nei vostri commenti. Potreste avere ragione nel pensare che aggiungere riferimenti al numero di linea rende il vostro codice molto più facile da capire. Questo se siete sicuri che il vostro codice non verrà mai modificato.