PowerShell: Comments

You've read the title. Comments. How can I fill an entire article with information on PowerShell comments? Prepare yourself to be amazed. There is a lot you can do with comments besides short one-liners. We can make large multi-line comments for documentation purposes and collapsible sections using regions. As a lover of documentation, I'll run you through some things that I try to do in all of my scripts.

Comment Etiquette

We will start with simple comments. Using # will block out a line from processing. Anything you type following a # on the same line is skipped when run. This lets you put documentation, explanations, notes, etc. within your script. You can see an example below. You can also use a comment to "activate" a part of a script. This can be useful for testing. Rather than adding and removing parts for testing, just comment them out and make a note of it. I also like to differentiate notes from something that is commented out. I will typically precede a comment explaining the next line(s) of a script with ###, rather than a single #, and a single # is reserved for blocking out pieces used solely for testing.

### Query all AD users
Get-ADUser -Filter * #| select -First 10 ### Remove # before pipe for small-batch testing

###Remove the first comment to "activate" the Select-Object
Get-ADUser -Filter * | select -First 10 ### Remove # before pipe for small-batch testing

Removing the # before the pipe will include the Select-Object, limiting the query to the first 10 user objects. If you have a complex query with calculated properties that you haven't tested yet, for example, it may benefit you to not test that query on a large batch of objects. A misconfigured calculated property in a query on tens of thousands of objects could potentially mean a few wasted hours, whereas a test run on 10 objects will be completed in a relatively short period of time, giving you more time to fix your mistake before a full run. Because of the second inline comment, preceded by ###, you will not have to remove the note. Everything before a comment will still run if there is no comment before it. Just be sure to add the comment back in before throwing your script into production.

Documentation

Another nifty use of comments is documentation at the top of your script. If you develop scripts for your organization or team to also use, you will want others to be able to understand what is happening. You can do this with inline comments but adding a multi-line comment to the top can help others quickly understand what is being done and hopefully mitigate a lot of questions. You can begin a multi-line comment with '<#' and end it with '#>'. You can place whatever you feel is necessary within this block. What I normally see and what I make a habit of including is a synopsis, a more detailed description or step-by-step explanation of the workflow, and a statement of ownership in some form, usually along the lines of "Email me if errors occur". See below for an example.

### Use a multi-line comment for documentation
<#
    Synopsis:
        TLDR of what this script does

    Workflow:
        1. First step script takes
        2. Second Step
            2a. Substep or explanation
        3. Third step

    Email [email protected] if errors occur
#>

Multi-line comment blocks are obviously not limited to documentation. If you have multiple lines of a script that you do not want to process, or you don't need those lines anymore but feel they may be needed in the future, you can wrap them in a multi-line comment block rather than putting a # on each individual line.

Regions

The last thing I want to cover is regions. A region is a special type of comment that makes collapsible sections in your script. It will not change processing but may make organization a little easier. I find regions incredibly helpful on longer scripts because each section can be a little more recognizable and if I'm editing one particular section, I can collapse the others to get them out of the way. Once they are collapsed, they will be less distracting and less prone to mistakenly being altered.

To make a region, you will need to specify the beginning with '#region RegionName' and the ending with '#endregion RegionName'. The name of the region must match to work, and #region and #endregion must be the first thing on their respective lines. They can be followed by comments, but they cannot have anything before them. Regions can also be nested within other regions. Once you have a valid region, you will notice collapsing arrows next to the line number. If you click the arrow, the region will collapse each line between #region and #endregion. Pay attention to how you nest them and use descriptive names. Copy the example below and try it out for yourself.

### Use regions to collapse multiple lines of a script
#region Processing
#region Query
$users = Get-ADUser -Filter *
#endregion Query

#region Output
Write-Output $users
#endregion Output
#endregion Processing

Conclusion

While this was a shorter article, it is an important topic. If you are making your own scripts and putting them in Azure, or sharing them with others for them to use, or doing something nice for another team by helping them automate something, you should be adding comments. Passing off a script with no documentation can cause problems down the road if something were to not work. You may receive questions that could have been answered in a comment. I view it as a "give a man a fish" versus "teach a man to fish" type of dilemma. If you leave your team or organization, the ones still using your scripts will have the resources to keep going on their own.

If you have some more specific uses for comments in your scripts, I'd love to hear them! Reach out to me at [email protected] or on LinkedIn.