Commenting on your code : how and why?

I. Introduction

Whether you're using PowerShell or another language, comments are a good practice. A comment is a portion of text included in your code that will not be executed when the PowerShell script is run. Comments are there to document the code and explain the purpose of a line or several lines, with the aim of explaining how the code works.

II. Why comment on your code?

We can put forward several arguments to encourage you to comment on your PowerShell code.

• Understanding: comments help you understand what the code is doing, which is particularly useful if the code is complex or contains a large number of lines. They can explain the purpose of a variable, your reasoning or details about the context of use.

• Maintenance : comments facilitate code maintenance. Indeed, if you or someone else needs to reread the code or make it evolve in several weeks or months, it will be easier to understand the logic of the script and how it works if the code is well commented.

• Teamwork : comments are essential when collaborating on code with others, especially your colleagues. They help others to understand your code more quickly and easily.

III. How do I comment on my code?

Now that you're convinced of the benefits of commenting your PowerShell code, you might be wondering how to go about it. In PowerShell, you can comment your code using the "#" character. Anything following this character on the same line is considered a comment.

# This command is used to check whether the notepad process is running on the machine.
Get-Process -Name "notepad"
# This is another comment

To temporarily disable the execution of a line, you don't have to delete it: you can comment it out temporarily.

You can also create multiline comments, or a block of comments, using the symbols "<#" and"#>" to mark the beginning and end of the comment.

<# This is a commentary
extending over
several lines #>

Whether in Windows PowerShell ISE or Visual Studio Code, comments are highlighted in the code using syntax highlighting. The color green is associated with commented lines.

IV. Comment-based help

In a PowerShell script, comments can be used to integrate help within the file itself. In fact, by using the syntax described above to create a comment block, we can add complete help to a script (or within a function). The Get-Help command will then be able to consult and interpret this help.

The syntax is as follows:

<#
.<Keyword>
<Help content>
#>

# PowerShell code

We can see that there are two pieces of information to indicate: the keyword preceded by a dot, and the text associated with this keyword, i.e. this section of the help. Here are the main words you can use:

Keyword	Description
.SYNOPSIS	Short description of the script or function
DESCRIPTION	Long description / detailed description of script or function
.PARAMETER	Description of each script or function parameter
.EXAMPLE	One or more examples of how to use the function or script. Can be accompanied by an example of output and a comment.
.INPUTS	Types of .NET objects accepted as input by this script or function
.OUTPUTS	Types of .NET objects output by this script or function
.NOTES	Additional information such as author, author's website, creation date, version history, etc.

In a script named "demo.ps1", we'll add the lines below to create the "SYNOPSIS" help section and associate a text with it. Which gives:

<#
.SYNOPSIS
This demonstration script explains how comment-based help works
#>

# Code PowerShell

After saving the file, we can read the help with Get-Help :

Get-Help .demo.ps1

If we look at the returned result, visible below, we can see that the"SYNOPSIS" section contains the text of our help! The"DESCRIPTION" section is empty, as we didn't fill it in.

Here's a more complete example from one of my scripts (which you can find on GitHub):

V. Conclusion

By adding comment-based help at the beginning of your script and embedding comments above your lines of code, you'll be able to document your script with ease. Even if it's time-consuming to add comments, keep in mind that it's a valuable aid to you, your colleagues and the community should your script be shared.

---