I’ve talked about SQL Server comments before and how important they are. In PowerShell comments are important for all the same reasons and then some. So first of all in SQL Server we use the following for comments:

-- Line comment
/* Block comment */

In Powershell we use these:

# Line comment
<# Block comment #>

Commenting your code, still super important. That piece of code that looks a bit strange because you couldn’t find another way to make it work? Better put in a note why so the next person doesn’t have to spend hours figuring out what you did and why. That block of code that pulls a list of zip files and unzips them? Explain what you are doing. The next person to look at this (who just may be you) could use a hint as to what you were thinking. Weird variable name? Heck, not so weird variable name. It couldn’t hurt to explain the purpose. Did I ever tell you I got a job because I did such a good job commenting my code during a technical test?

Interestingly though PowerShell has a really cool trick that makes comments even more useful and important.

A properly set up comment block gets picked up by Get-Help to create comment-based help. For example:

function Get-Function { }

<#
.description
This is what Get-Function does.
#>

Now if you use Get-Help on Get-Function you have a description section. These aren’t exactly complicated, but on the other hand they do appear to be somewhat fiddly. Rather than go over in detail how this works I’m going to recommend that you follow the link above and read about it.