PowerShell code tells you how, but the PowerShell comments tell you why. Here are the ways to comment your PowerShell and some accompanying best practices.
Mystery code
Here is a scenario all too familar: You are heads down, writing an awesome script. Since you are writing it you know exactly how it works and why you made the design decisions you did. You are so clever! The code is so obvious that it pretty much explains itself to someone reading it.
Now here’s how reality usually goes: A peer needs to make a change to your script. They wonder what the variable name $m represents. They try to trace flow of your script, constantly having to scan to find the function definition you created. Why did you create a special function for that? Couldn’t that be done with the <insert applicable cmdlet name here> cmdlet? What are the prerequisites for this code to run? Does it require a minimum version level of PowerShell? And the questions go on and on.
Even if you as the author come back to review it months down the road, can you reliably remember the logic you used to design and write it?
Adding comments give your script understanding
A good comment:
- Explains the logic of the script. For example, if data is returned in a particular format, and it needs grooming prior to use, explain that logic in a comment. This includes business rule logic.
- Enable predictable changes in the future. If you understand the logic requirements when the script was created, you will more easily understand changes needed when those logic requirements change.
- Simplify troubleshooting in the future. Again, understanding the logic let’s a human more easily find faults in the logic and fix them.
Add a PowerShell single line comment
Adding a single line comment in PowerShell is easy. Begin the line with #, followed by your comment text. In PowerShell ISE, it will be color highlighted as green.
# This is a single line comment. # This is another single line comment.
If you have a longer comment to include, you would rather display it as a readable paragraph. You could use a bunch of single line comments, but you have to manually adjust the comment text, and it won’t read well due to the # at the beginning of every line. Look at the following example:
# Business Logic Rule # This particular function is derived from our company Policy and Procedure number # 24, section 2. All user accounts that have not logged in to a computer within # 90 days should be disabled automatically, and an email alert sent to the head of IT # Security informing them of the action taken.
It is readable, but it could be optimized. Also, if you have a bunch of comments like these, that is a lot of extra scrolling you have to do. Both readability and scrolling bloat can be addressed with a multi-line comment.
Add a PowerShell multi-line comment
Adding a multi-line comment in PowerShell is almost as easy. This time, two tags are required, an opening comment tag, <#, and a closing comment tag, #>. It will be color highlighted as green too.
<# Business Logic Rule This particular function is derived from our company Policy and Procedure number 24, section 2. All user accounts that have not logged in to a computer within 90 days should be disabled automatically, and an email alert sent to the head of IT Security informing them of the action taken. #>
You can also collapse the multi-line comment for easier reading, expanding it only when needed.
Commenting Best Practices
Misusing or abusing the comments feature can have a negative impact on understanding your script. Here are some recommended rules to keep in mind when deciding whether or not to add a comment:
- Do not add a comment to explain basic PowerShell knowledge a likely reviewer would already know.
- A comment should explain the logic being implemented, especially if it is unique or related to a business rule.
- Comments should be as close as possible to the code they describe.
- Avoid complex formatting of comments. The more formatting rules you try to enforce, the less likely they are to be adhered to and may discourage commenting overall.
- Don’t include redundant information. For example, if you are checking your code into a version control system, the script itself doesn’t need a revision history.
- Document in code first, and comment last. For example, use descriptive variable and function names to help a reader understand the parts in play.
Go forth and comment
Now that you know the basics of commenting, make a dedicated effort to incorporate to your daily coding practices. You will be glad you did when you revisit that code in a year!