Hey, Scripting Guy! How Can I Add Multiline Comments to My Windows PowerShell Scripts?
Hey Scripting Guy! I have been trying to add more comments to my Windows PowerShell scripts, but one thing that I really miss is a multiple-line comment character that I had in other programming languages. Not having a multiple-line comment was annoying in VBScript, but it is unacceptable for Windows PowerShell to not have it. Let’s face it, lots and lots of # characters looks messy, and are time consuming to type.
Microsoft Scripting Guy Ed Wilson here. I am listening to Kenny Wayne Shepherd on my Zune HD while sipping on a cup of Earl Grey tea with some lemon grass and cinnamon in it. I spent several hours this morning reviewing the tags for the Hey, Scripting Guy! blog posts on the TechNet Script Center. Someone on Twitter asked me why I was retagging Hey, Scripting Guy! blog posts, and there are actually two answers to that question. The first is that it needs to be done to ensure the articles are easily found. The second reason is that it is fun. There have been some really amazing scripts written in the last 5-1/2 years.
Note: Portions of today’s Hey, Scripting Guy! post are excerpted from the Microsoft Press book, Windows PowerShell 2.0 Best Practices by Ed Wilson, which is now available.
JF, even though many scripts can be written without a multiline comment, you will be glad to know that Windows PowerShell 2.0 has introduced multiple-line comments.
Windows PowerShell 2.0 solves the problem of multiline comments by including the multiple-line comment tags. The opening tag is the left angle bracket with a pound sign (<#), and the closing comment tag is the pound sign with a right angle bracket (#>). The pattern for the use of the multiline comment is shown here:
<# Opening comment tag
First line comment
Additional comment lines
#> Closing comment tag
The use of the multiline comment is seen in the DemoMultiLineComment.ps1 script.
“The above is a multi-line comment”
When the Demo-MultiLineComment.ps1 script is run, the two cmdlets that are seen inside the comment tags are not run; the only command that runs is the one outside the comment block, which prints a string in the console window. The output from the Demo-MultiLineComment.ps1 script is seen here:
The above is a multi-line comment
The multiline comment tags do not need to be on individual lines. It is perfectly permissible to include the commented text on the line that supplies the comment characters. The pattern for the alternate multiline comment tag placement is seen here:
<# Opening comment tag First line comment
Additional comment lines #> Closing comment tag
This is seen in Multi-Linedemo2.ps1.
“The above is a multi-Line comment”
As a best practice, I prefer to place the multiline comment tags on their own individual lines. This makes the code much easier to read, and makes it easier to see where the comment begins and ends.
When the Multi-LineDemo2.ps1 script is run, the following output is seen.
You can even use the multiline comment syntax to comment a single line of code if you wish to do so. The pattern for this type of comment is seen here:
<# Opening comment tag First line comment #> Closing comment tag
An example of this use in a script is seen in the Multi-LineDemo3.ps1 script.
<# This is a single comment #>
“The above is a multi-Line comment”
The output from the Multi-LineDemo3.ps1 script is seen in the following image.
One thing that is important to keep in mind with the multiline comment pattern is that anything placed after the end of the closing comments tag will be parsed by Windows PowerShell. Only items placed within the multiline comment characters are commented out. When phrased like this, it makes sense, but the behavior is completely different than the pound sign (#) single-line comment character. It is also a foreign concept for users of VBScript who are used to the behavior of the single quote (‘) comment character in which anything after the character was commented out. A typical use scenario that generates such an erroris illustrated in the following example:
This example causes an error
The error that is generated by the above command is shown in the following image.
If you find yourself in a situation where you need to highlight your comments in the above manner, you only need to change the position of the last comment tag by moving it to the end of the line to remove the error. The modified comment is seen here:
This example does not cause an error
No space is required between the pound sign and the following character. I prefer to include the space between the pound sign and the following character as a concession to readability.
As seen in the following image, no output is displayed from a multiline comment.
The single pound sign (#) is still accepted for commenting, and there is nothing to prohibit its use. To perform a multiline comment using the single pound sign, place a pound sign in front of each line that requires commenting. This pattern has the advantage of familiarity and consistency of behavior. The fact that it is also backward compatible with Windows PowerShell 1.0 is an added bonus. This is seen here:
# First comment line
# additional commented line
# last commented line
JF, that is all there is to using the Windows PowerShell 2.0 multiple line comment characters. Windows PowerShell Help Week will continue tomorrow.
If you want to know exactly what we will be discussing tomorrow, follow us on Twitter or Facebook. If you have any questions, send e-mail to us at email@example.com or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson and Craig Liebendorfer, Scripting Guys