Organize Your PowerShell Code With Regions and Multiline Comments

Introduction

When learning any scripting or programming language, we are always told that comments are extremely important, they are essential for code readability and maintainability. Well, PowerShell is no exception to the rule and fortunately there are "tricks" that make it easy to add comments to source code. In this post we will go over two great features: code regions and multiline comments.

If you are familiar with PowerShell you probably know that the '#' sign marks the beginning of a comment. Let's now dive into less commonly known, yet very useful ways to add internal documentation to our PowerShell code.

Code Regions

Code regions let us create blocks of code delimited by an opening and closing comment line. They are ideal to define sections containing consecutive lines of code, which accomplish a common purpose, or are somehow related. A region starts with the regular comment character (#), followed by the word 'region'. Optionally, (and strongly recommended) we can complement the opening line with additional text to document the region's code. For example: #region report generation. Now, to end the region, we just need to add a line containing '#endregion', of course we want to be consistent so we should also add the description: #endregion report generation. Here is an example:

Write-Host "Script execution started at $(Get-Date -Format 'HH:mm:ss')"

#region report generation
$Computers = Get-Content -Path C:\MyServersList.txt

foreach ($Computer in $Computers) {

    Get-EventLog -LogName System -ComputerName $Computer -Newest 25 -EntryType Error |
    Select-Object -Property MachineName,EventID,Message,TimeGenerated |
    Export-Csv -Path C:\EventLogReport.csv

}
#endregion report generation

Write-Host "Script execution finished at $(Get-Date -Format 'HH:mm:ss')"

So we added an opening and closing comment line, it doesn't seem that useful though. However, you might notice (in ISE, VS Code, etc.) a '-' sign or folding icon next to the '#region' line. If you click on them the region will collapse, hiding all the lines within the 'report generation' region, letting you focus on the rest of the code that is still visible. This code snippet will not display this behavior but you can copy an paste it into your code editor, you will see something like this:

That's an example of an expanded and collapsed region.

Obviously, you can have as many regions as you want, which is a great way to document and organize your code.

Multiline Comments

As mentioned before, to insert a comment anywhere in the code of a script, function, module, etc. we use the '#' character. If we needed to insert a comment that spans across various consecutive lines we can simply start each line with a '#'. But, there is a better way.

Like regions, multiline comments have opening and closing characters. It starts with '<#' and ends with '#>'. Let's see an example.

<#This is the start of the multiline comment block.
This is the second line.
This is the third line.
And this is the last line.#>

#-----------------------------------------------------

<#
This is the start of the multiline comment block.
This is the second line.
This is the third line.
And this is the last line.
#>

We can start the comment block right after the '<#', or in the next line. We can also place the last line of the comment the line before '#>', or in the same line. Multiline comments are ideal for comment-based help.

Conclusion

Internal documentation is extremely important when writing code. In PowerShell we can use the regular comment lines, preceded by a '#'. But, in addition, we can take advantage of code regions and multiline comments to organize our code, and make it look neat and tidy. Multine comments are used to write comment-based help. If the editor supports it, both features provide code-folding capabilities.

Feel free to leave comments and questions below and thanks for reading this far.