PowerShell Comments

When we are scripting in general, it is essential to write comments within the script. Comments help us in a lot of aspects. As in every scripting language, PowerShell is no different. In this post we will discuss only about PowerShell comments and how we will use them in our scripts.

Reasons for commenting

Comments in our scripts will help others and ourselves to get more information regarding a script. Some of the reasons that someone writes comments in a script are:

• Provide information of what a command/function is doing
• Provide information on why a specific command/function was used
• Deactivate commands temporarily while troubleshooting
• Provide general description for the script
• To be used as reminders

When we are trying to edit our scripts in the future, comments will remind us in a certain way what we were thinking at the time we were writing the script. This applies also when others will try to edit or fix the script that we wrote, in the future.

Write helpful comments

Although comments need to provide enough information to be helpful, they should not overwhelm the script. It will make the script very difficult to read. Imagine that you have to read the below sample script.

# Using the below command I am getting
# the script will prompt the user to write his
# input. Then I save the input in a variable
# called $userinput.
$userinput = Read-Host "Please enter whatever you want"
# After the $userinput command is filled with the value
# of the user. I am using the Write-Host command to
# show the value of the $userinput variable into the console.
Write-Host $userinput

The above script is only two commands and comments are another seven lines. Image that you have a bigger script using so many comments. You will lose the actual commands within the comments. So the comments that you write needs to be brief but include as much information to help you understand and remember what you were doing. Below is the same script with the same information in comments but slightly different and much easier to read.

# Read the input from a user which will be saved in a variable
# and present in the console.
$userinput = Read-Host "Please enter whatever you want"
Write-Host $userinput

As you can see, writing only the information that is needed in the comments and keep only the information that is really necessary, will keep your script more compact and much easier to read in a later stage.

Comments syntax

Single line comment

In PowerShell v1.0 we are able only to write comments using the # symbol, line by line. If you had you write multi-line comments you had to use the # symbol at the beginning of each line. Anything after # is ignored, and this will allow us to write our comments. Below is an example on how it is done.

#This is a single line comment in a script
$a = "Hello World"
Write-Host $a

You are also able to add some comments at the end of a command like the example below. Please have in mind that comments are recommended to be placed above the code as it is easier to read. Adding comments at the end of the line should be done only if it is completely necessary.

$a = "Hello World"
Write-Host $a # This is a comment

Multi-line comment – Block of comments

With PowerShell v2.0, multi-line or block comments have been introduced. With multi-line commenting you are allowed to have comments in a big blocks using multiple lines without the need of using # symbol at the beginning of every line. It allows you to enclose your comments between <#….#>. The example below shows you how this can be done.

<# The text in here will all be considered
as comments. It does not matter of how many lines
it will take, as long as it is within the symbols #>
$a = "Hello World"
Write-Host $a

Block commenting also helps you to include comments between a command, without affecting it, as all comments will be ignored. The first example shows us the Write-Host command on multiple line using back tick for splitting the command, for those that use this method. The second example is exactly the same command but using splatting. I will not discuss further for the methods of splitting commands in this post. There will be a separate post for this subject. Let see below some examples.

These are the commands that we are using without any comments

$a = "Hello World"
Write-Host $a -ForegroundColor Green -BackgroundColor Red

Lets add some comments for the parameters of Write-Host command

Example 1

$a = "Hello World"
Write-Host $a <# Message #> `
-ForegroundColor Green <# I love Green #>`
-BackgroundColor Red # I love Red

Example 2

$a = "Hello World"
$Parameters = @{Object = "$a" # Message
ForegroundColor = "Green" # I love Green
BackgroundColor = "Red" <# I love Red #>}
Write-Host @Parameters

As you can see from the two examples above, when the comments are at the end of the command, we can use only # to write our comments. If after the comments on the same line, there are more parts of a command, we have to use the block commenting method in order to ignore only the part that is enclosed within <# #>.

In conclusion, commenting in your scripts is helpful. It should be brief and informative and use them in a way that you will be able to read the script easily and they will not affect it.

Let m know your thoughts and comments. You feedback is really appreciated.

Related Links:

• PowerShell Tutorials
• What is PowerShell
• Useful PowerShell commands
• Write-Host – Microsoft Docs

Summary

Article Name

PowerShell Comments

Description

PowerShell Comments. This tutorial will provide you information about commenting in PowerShell. It will help you about the information that you need to include in them while setting them up and how this can be done. Stephanos Constantinou Blog - PowerShell Scripting

Author

Stephanos

Publisher Name

Stephanos Constantinou Blog

Publisher Logo