Updated March 6, 2023
Introduction to PowerShell comment
For any programmer, commenting on the code is as important as the functionality of the code. Commenting is an important of programming as it helps programmers to understand the code and functionality that is developed by some other programmer. Writing descriptive and insightful PowerShell comments in scripts helps us humans understand the code’s meaning, the effect, and possibly explains edge cases that have arisen in the past. This article will cover in detail about different types of comments, when and where to use which one them effectively in scripts in detail.
Syntax:
In PowerShell to comment, # is used. Everything that follows # in the same line is considered a comment by the PowerShell interpreter. This is used for single-line commenting, for multi-line commenting, or a comment block <#….#> is used.
Eg:
#example of single ling comment
Write-Host "The above line won't be printed"
<#
the below lines
won't be printed"
#>
Write-Host "above lines are example of multiline comment r script block"
Output:
Commenting out using shortcuts:
To individually comment out each line (#), select one or more lines and press Ctrl + Q, or click Comment (in the Edit section of the Home tab). Highlight a code block and press Ctrl + Shift + Alt + Q, or select Block Message to add a comment block. (PowerShell Studio version 4.1.72 introduces the Block Comment icon.) To delete comments (in either format), select the lines to be deleted and press Ctrl + Delete. Comments can be deleted using Ctrl +shift+ Q or select the block and select uncomment from options window.
Adding Descriptive text for comments:
When you open the script to seek out what the script does, it sure would be nice if there are useful details listed inside like what the script is for like who created it, and when was it created. A block comment in PowerShell is beneficial for adding descriptive text in your scripts. This way, the aim of the script is already given and is additionally an excellent thanks to include warnings or things to observe out for when using the script.
Example:
<# This script will copy items from one site collection to another.
WARNING: Don’t run this in production using system account.
Last update: Feb 14, 2021
Last Updated By: Vignesh Krishnakumar
Last run time: 1 hour 30 mins
Duration: Run every month 15th
Inputs to be supplied: Source site, destination site
Output location: C:\output
#>
Creating comments for documentation purpose:
Sometimes, the script should be run in a way or an order. It will be not be known to a person who has not developed it. In that case, documenting the steps inside a script block will be useful.
Example:
Input:
<#
This function fetches credentials from an XML file in an encrypted way to connect to the system
In case XML file is not there, please do the below.
1. Open PowerShell as an administrator
2. Run this command – ‘Get-Credential | Export-CliXml .\test.XML’
3. Save the output in the same folder as the script.
4. Once the credentials are received call the main function
5. Once the script is run successfully go and check the logs in the log path
6. In case of any errors copy the id and go and check in CRM
NOTE: This will work only in the same computer
#>
Best Practices for commenting
Never use line number in comments:
When writing code, you would possibly be tempted to feature regard to a line number in your comments. you’ll be right in thinking that adding line number references makes your code that much easier to know. that’s if you’re sure that your code will never be modified. Imagine that a replacement line of code is inserted into your script. This can mean that each one of the road number references in your comments already got shifted. And to stay the road numbering accurate, you’ll need to edit the comments to update them one by one.
Do not add comments at the end of a script:
Generally, a code is read from top to bottom. If the comment you’re adding is vital for the succeeding lines of codes, then it’s only logical to feature the comments before. After all, if you’re adding comments within the script about the script, isn’t it more sensible to possess the comments before the code and not after?
Avoid comment at the end of a line:
Same as the above point, putting comments after the code, albeit it’s on an equivalent line, is not any better than placing the comment below the code. Adding comments at the top of the code can cause editing errors because rather than being focused on modifying the code, you’d even have to mind that the comment moves along because the code changes.
Avoid comments if not needed:
Sometimes the code is too simple and therefore the intent is already too obvious that adding a comment there is simply a waste. Generally during this situation, a comment might be even longer than the code that it refers to. An obvious command with a comment. If you think that the code is self-explanatory, you’ll want to think about skipping adding a comment.
Comment based help for functions and scripts:
Comment-based assistance is written as a series of comments. All the lines within the comment block are interpreted as comments. All the lines during a comment-based help topic must be contiguous. If a comment-based help topic follows a comment that’s not a part of the assistance topic, there must be a minimum of one blank line between the last non-help comment line and therefore the beginning of the comment-based help. Keywords define each section of comment-based help. Each comment-based help keyword is preceded by a dot. The keywords can appear in any order. The keyword names aren’t case-sensitive. For example, Description keyword precedes an outline of a function or script.
Conclusion
Thus, the article explained in detail about commenting or comment block in PowerShell. It also explained the various shortcuts that are available and usage of each comment type. To learn more in detail it is advisable to write sample scripts and practice them.
Recommended Articles
This is a guide to PowerShell block Comment. Here we discuss Introduction, syntax, and How filter function works in Kotlin? with examples. You may also have a look at the following articles to learn more –
Recommended Articles
This is a Guide to PowerShell block Comment. Here we discuss Introduction, syntax, and parameters, examples with code implementation. You may also have a look at the following articles to learn more –
