No Comment(ing)? Not in PowerShell

Writing a script can be hard, making it reusable a bit harder and having someone else understand it’s purpose one of the hardest things you can do. To make your life and their life easier, the use of Comments is an easy way to enhance or augment a script. Below are a few examples of Commenting in PowerShell, the list is not exhaustive, but merely instructive.

Examples of Comments

Script Sections

One way to help someone parse a script and its purpose is to label sections of the script – variables, functions, main body, etc. Like so:
[sourcecode language=”powershell”]
# Variables
$NumberOfMailboxes = 0
$Failed = $False
$UserCount = 0
# Email Process
Send-MailMessage -To $To -From $From -Subject $Subject -Bodyashtml -Body $Body
SMTPServer $SMTPServer -Credential $SMTPCred -Port $Port -UseSsl
[/sourcecode]
Comments can also be used to provide a detailed description of the script and is usually placed at the beginning of your script:
[sourcecode language=”powershell”]
##########################################################
# SCRIPT DETAILS
# This script drives a menu to run Active Directory health check scripts.
# #
# SCRIPT VERSION HISTORY
# Current Version : 1.5
# Change Log
# :1.5 – fixed bugs, improve reporting
# : 1.4 – Added GPO check, fixed DNSLint issues
# : 1.3 – Tweaks and bug fixes
# : 1.2 – Removed deprecated tools
# : 1.1 – Added more AD Information and a fix for remote PS
# : 1.0 – First version
#
# OTHER SCRIPT
# Wish list : More tests, change some tests to export to HTML
# Rights Required : Enterprise Admin / Domain Admin
# Author : Damian Scoles
# My Blog : http://justaucguy.wordpress.com
#
# Disclaimer: You are on your own. This was not written by, supported
# by, or endorsed by Microsoft.
#
# EXECUTION
#. \ActiveDirectoryHealthCheckMenu.PS1
#
##########################################################
[/sourcecode]
Comments can also be used to describe a function’s purpose:

This function checks for hotfixes needed in order to install corporate applications
[sourcecode language=”powershell”]
Function HotfixCheck {
# Check to see if the hot fix is installed
$Hotfix = Get-Hotfix | Where {$_.HotFixid -eq "KB3146714"}
# If the $Hotfix variable is empty, no hotfix is installed, then install the hotfix
If ($Hotfix -eq $null) {
# Set value of command to run to install the KB38146714 hotfix
[String]$Expression = "wusa.exe .\Windows8-RT-KB3146714-x64.msu /Quiet /NoRestart"
# Runs the install process
Invoke-Expression $expression
}
} # End HotfixCheck Function
[/sourcecode]
As you can see, comments are an easy add to your PowerShell script and can serve many purposes. We write about this in our Exchange 2016 and Exchange Online books, so visit our shop to pick up your own copy for reference today.