Hey, Scripting Guy! How Can I Add Multiline Comments to My Windows PowerShell Scripts?

Hey, Scripting Guy! How Can I Add Multiline Comments to My Windows PowerShell Scripts?

  • Comments 4
  • Likes

Bookmark and Share

 

Hey, Scripting Guy! Question

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.

-- JF

Hey, Scripting Guy! AnswerHello JF,

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.

Image of Windows PowerShell 2.0 Best Practices book

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.

Demo-MultilineComment.ps1

<#
Get-Command
Get-Help
#>
"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.

Multi-LineDemo2.ps1

<# Get-Help
   Get-Command #>
"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.

Image of script output

 

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.

Multi-LineDemo3.ps1

<# 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.

Image of ouput from second script

 

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.

Image of error generaed by above command

 

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.

Image of no output displayed by 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 scripter@microsoft.com or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

 

Ed Wilson and Craig Liebendorfer, Scripting Guys

 

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • <# #> is all you had to say. The size of this blog post is pretty unnecessary.

  • If you're stuck in an environment where Powershell 2.0 is too derned newfangled, this post explains how to use single-line comments while retaining the auto-documentation goodness:

    powershell.com/.../making-comment-based-help-compatible.aspx

  • @oscar

    That post is kind of misleading.

    The issue has come up recently and repeatedly.  Multi-line comments are used in nearly all higher level languages and in the C language and derivatives.

    The comment documentatiuon style is much simplified over C and other languages which use a very heavy XML based method enclosed in a comment; single or multiline.

    PowerShell is just continuing this very popular mechanism and simplifying it.

  • I believe that block comments are evil and have written a keyboard shortcut for PowerShell ISE to make doing multiple single-line comments a breeze, as this functionality is provided in most PS IDEs except for ISE. Check it out at blog.danskingdom.com/powershell-ise-multiline-comment-and-uncomment-done-right-and-other-ise-gui-must-haves