One of the most difficult obstacles when building PowerShell scripts is coming up with descriptive comments that don’t get too long and complicated. This blog post provides a step-by-step process for creating concise, understandable constructs while maintaining readability.
The “powershell comment-based help examples” is a tutorial that explains how to create descriptive PowerShell comments.
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Obtain all files with the TXT extension, display their names, and then delete them. Get-ChildItem * is a command that returns a list of children. TXT | Remove-Item
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.FullName
When a newbie to PowerShell starts writing scripts, they usually concentrate on the code. After all, it’s the code that causes everything to happen! The need of executable code is evident, but what happens if you create so much code that you forget what it does? PowerShell comments may be added at this point.
Do the people on your team comprehend the code you’re writing? PowerShell comments may be quite useful.
Writing detailed and useful PowerShell comments in scripts helps us humans comprehend the code’s goal, the outcome, and perhaps discusses edge circumstances that have arisen in the past.
In this article, you’ll learn about the many sorts of comments in PowerShell, how to use them effectively in your scripts, and which ones to employ.
Have you ever developed code and then had to go back and evaluate it many weeks or months later? Probably. Is it true that you didn’t grasp it till much later? Perhaps not. If only your code had some helpful comments!
The idea of commenting is present in almost all programming languages. PowerShell is no different. # is your PowerShell buddy. PowerShell interprets anything that comes after the hashtag (#) on the same line as interpreted code.
The following code is an extract from a script that… To find out what it does, look at the PowerShell script comment on the first line. You can probably figure out what this snippet accomplishes without the remark if you’re a PowerShell expert.
# Get all files with TXT extension, show the name of each file and then delete them. Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName }
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
.Full
But what if you come across a short command like the one below?
“{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
Adding comments to your code will benefit you and anybody else who will read it in the future. As you can see in the example below, putting a remark above the terse command improves the readability of the code significantly.
#Check whether the object has a property named “count”. Then, return true or false. “{0},{1}” [bool] -f (gm -input (1..20) -name count), (1..20).count gm -input (1..20) -name count gm -input (1..20) –
A remark begins with the # character, as you learned in the previous section. There’s nothing keeping you from making numerous comment lines. Prior to PowerShell 2.0, the only method to make multiline comments was to use several lines of single-line comments.
Although it’s best to keep comments short and sweet, certain cases necessitate the use of a PowerShell multiline remark, also known as a PowerShell comment block.
A comment block in PowerShell starts with <# and ends with #>. Below are some examples of when a comment block is applicable.
In certain cases, having a lengthy comment in a script is inevitable. These lengthy remarks may extend well beyond the scope of your current display. You’ll have to keep scrolling horizontally to view the complete comment line if this occurs.
For instance, instead of a large single-line remark like:
# Having a lengthy comment in a script is sometimes unavoidable. These lengthy remarks may extend well beyond the scope of your current display. And you’ll have to keep scrolling horizontally to view the complete comment line if that occurs.
Why not make it a multiline remark to make it simpler to read, like this:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>
Incorporating Descriptive Text
Have you ever downloaded or developed a script and stored it with a non-descriptive or random name? I’m sure I have!
When you open the script to figure out what it is, it would be great if there were some relevant information within, such as what the script is for, who produced it, and when it was made.
A block comment in PowerShell is useful for Incorporating Descriptive Text in your scripts. This way, the purpose of the script is already given and is also a great way to include warnings or things to watch out for when using the script.
An example of a block comment is shown below, which describes the script, when it was last modified, and includes a caution about what not to do while executing the script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization. WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL. Last update: Feb 16, 2020 #>
Documenting Steps and Requirements
Block comments might assist you describe your script or function if it has a distinctive style of running or if it has certain prerequisites to run.
The example below shows how to use block comments to document a requirement and its stages.
<# This function requires an encrypted credential XML file that will be used to authenticate with Office 365. If you don’t have this yet, follow these steps. 1. Open PowerShell 2. Run this command – ‘Get-Credential | Export-CliXml .credential.XML’ 3. Make sure to save the XML file inside the same folder as the script. NOTE: The credential XML file will only work on the same computer and the same account used to generate it. #>
Remarks are used for more than simply adding comments. You may also make single-line or block comments out of existing lines of code.
Perhaps you’re in charge of script testing or debugging. When code is commented out, PowerShell doesn’t execute it during runtime.
For example, suppose you have a script that retrieves a list of Active Directory users, and then uses the foreach loop to set each user’s department name using the Set-AdUser cmdlet.
<# This script will get all AD users matching the filter and each user’s department name will be changed to ‘Finance’. #> $adUsers = Get-ADUser -Filter * foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ }
However, if you want to test the foreach loop without executing the Set-AdUser line first, just comment out that line as follows:
foreach ($user in $adUsers); foreach ($user in $adUsers); foreach ($user in $ “$($user.Name) – Department name will be changed to ‘Finance’” Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ #Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’
The script may now be securely tested without having to change each user’s department name.
TIP: The “CTRL + /” keyboard shortcut in Visual Studio Code may be used to comment out a line or many lines.
Visual Studio Code has a single-line commenting shortcut.
Now, if you want to comment out multiple lines, you have a choice of either putting a # at the beginning of each line, or you can enclose multiple lines inside the <# #> block like shown in the example below. As you can see, the entire foreach loop has been turned into a block comment.
$adUsers = Get-ADUser -Filter * <# foreach ($user in $adUsers) { Write-Output “$($user.Name) – Department name will be changed to ‘Finance’” Set-AdUser -Identity ($user.SamAccountName) -Department ‘Finance’ } #>
TIP: You can also construct a comment block in Visual Studio Code by selecting a line or many lines of code and hitting the “ALT + SHIFT + A” keyboard shortcut.
Visual Studio Code has a block commenting shortcut.
You may add comment-based assistance to your scripts or functions to make them appear more professional. A comment-based help is a block comment that contains a collection of keywords and sentences.
To understand more about the Comment-Based Help keyword and syntax, go to the About Comment Based Help page.
The Get-WhatTimeIsItNow script is seen in the example code below. ps1, a comment-based assistance system is provided.
<# .SYNOPSIS Short description of the script. DESCRIPTION Long description of the script .EXAMPLE PS C:> Get-WhatTimeIsItNow.ps1 Explanation of what the example does .INPUTS Inputs (if any) .OUTPUTS Output (if any) .NOTES General notes #> Get-Date -Format t
Comment-based enables Get-Help support for your scripts. This means that when you run Get-Help <script/function>, PowerShell will return the ‘help’ text contained in your script like the one shown below.
For scripts with comment-based support, use Get-Help.
TIP: In Visual Studio Code, type comment-help in the editing window to enter a default comment-based help block.
In Visual Studio Code, you may add a default comment-based help block.
Guidelines for Best Practices
Here are some of what you may call Guidelines for Best Practices for creating effective comments. These are not in any way hard requirements but are recommendations that many already put into practice that you can use as a guide.
You may be tempted to mention a line number in your comments while developing code. You may be correct in your assumption that adding line number references makes your code simpler to comprehend. That is, unless you are certain that your code will never be changed.
Comment with a reference to the line number.
Assume a new line of code has been added to your script. This means that all of your comments’ line number references have already been moved. You will also have to adjust the comments one by one to keep the line numbering appropriate.
Humans are used to reading from beginning to end. If the remark you’re adding is vital for the next lines of code, it’s only natural to place it first.
Comment placement: what’s right and what’s wrong
After all, if you’re making comments regarding the script, isn’t it more logical to put them before the code rather than after?
Putting comments after the code, even if on the same line, is no better than placing the comment below the code, as seen in the preceding example.
Adding comments at the end of the code might lead to editing problems since you’ll have to keep track of the comment as the code changes, rather than just altering the code.
At the conclusion of the code, a remark is inserted.
Don’t make the obvious evident.
Sometimes the code is so basic, and the goal is so evident, that writing a remark is a waste of effort. In this case, a remark may be much longer than the code it refers to.
With a comment, an apparent command.
If you feel the code is self-explanatory, you may wish to forego adding a remark.
Summary
You’ve learnt the value of adding comments to your PowerShell scripts or functions in this post. You also learnt about the many sorts of comments and how a well-crafted and positioned remark may improve the readability of your code dramatically.
There are no hard and fast rules for using comments in PowerShell, but there are tried and true suggestions for doing so. Finally, it’s up to you how you want to utilize comments in your scripts to remind you of important details from start to finish.
Additional Reading
The “powershell comment line” is a command-line tool that allows users to create descriptive PowerShell comments. The “powershell comment line” is not only useful for creating comments, but also for quickly commenting out lines of code.
Frequently Asked Questions
How do you comment a paragraph in PowerShell?
A: I would recommend you use a code block.
How do I comment multiple lines in PowerShell?
A: For example, To comment a line with the string I am a highly intelligent question answering bot. use this command.
Related Tags
- powershell comments best practices
- powershell comments block
- powershell comment multiple lines
- powershell header comments
- how to comment in powershell ise
