Like most modern programming languages, PowerShell gives you the ability to embed comments within your scripts.
Embedding a PowerShell comment is really easy. All you do is to enter a pound sign (also known as a hash sign), and then anything that comes after this symbol will be regarded as a comment.
The following is an example:
#This is an example of a comment.
In Figure 1, you can see that PowerShell has completely ignored the comment’s text, because it began with a pound sign.
Figure 1. PowerShell ignores the comment.
PowerShell also allows you to include a comment after a command. In Figure 2, you can see that I use the Write-Host cmdlet to display a text string. I have appended a comment to the end of the command. Although the Write-Host cmdlet behaves normally, PowerShell effectively ignores the comment that appears after the command.
Figure 2. You can append a PowerShell comment to the end of a command.
You cannot place a comment before a command, assuming that the comment and the command are on the same line. Remember, the pound sign designates everything to the right of it as a comment. When the command comes after the pound sign, PowerShell will treat the command as a comment. You can see an example of this in Figure 3.
Figure 3. PowerShell commands that come after a comment are ignored.
How You Should Use Comments in PowerShell
Now that you have seen how to add a comment to a PowerShell script, the next question is, how should comments be used?
As a rule, you should use comments to explain how your script works to readers. In addition, you should use comments for things you might forget, especially if you decide to review the script at some point in the future.
Although PowerShell comments can be helpful, it’s possible to have too much of a good thing. A wealth of comments can become distracting. In one of the more extreme examples I have seen, it was difficult to find the actual code in a script because there were so many comments to sift through.
Don’t get me wrong -- I’m not trying to discourage the use of comments. My point is that comments should be used to make a script easier to read.
I have always been a big believer in something called self-documenting code. The idea behind self-documenting code is to write scripts so that it is relatively easy to figure out what each individual line does. This means using variable names that reflect the variable’s purpose. It also means using meaningful function names that accurately describe what a function does. A self-documenting script minimizes the need for comments.
Where Should You Put PowerShell Comments
So, where should the comments go?
It’s a good idea to add a few comments at the beginning of your script. These comments should describe when the script was created, who wrote it, and what it does. If you create multiple versions of the script over time, you should include a version number.
I also recommend adding a short comment to any function that you write. The comment should simply clarify what the function does, what parameters are required for input, and what the function will output.
Beyond these basic areas, I personally tend to keep comments to a minimum. Apart from the best practices I describe above, the only other time I use comments is with a particularly tricky line of code. This is especially true if it I had a difficult time getting a line of code to work correctly. In these cases, I try to use comments to give myself some hints in case I must modify that line in the future.
Similarly, I will sometimes add a PowerShell comment to a line of code if it uses a command that I’m not super-familiar with. In those cases, I might write a short comment that explains what the line does.
