How to Add Comments in PowerShell Scripts?

Adding comments in PowerShell scripts is a great way to document your code and make it more readable for others (and yourself) to understand what your script is doing. Comments can be used to explain the purpose of a script, and the different parameters available, or to provide additional information about a script’s execution. Comments can also be used to provide instructions for other users who may need to modify or troubleshoot the script. In this article, we will discuss how to add comments to PowerShell scripts, single-line and multiline comments, best practices, and examples of how to effectively use comments in your code.

Why Comments are Important in PowerShell?

Comments are an important part of any programming language. They allow you to add notes and explanations to your code, making it easier to understand later. Comments can also help others understand what your code is doing if you need to share it. Here are some of the key reasons you should comment on your PowerShell code:

• Documentation – Comments act as documentation, explaining how the code works. This helps you and others understand the script logic later.
• Collaboration – Well-commented code makes it easier for teams to collaborate on PowerShell projects.
• Maintenance – Comments make ongoing maintenance and updating existing scripts much simpler.
• Learning – Comments are great for learning. You can annotate code samples from blogs and books.
• Enhanced Readability: Comments illuminate the script’s intent and logic, making it easier for both the scriptwriter and others to understand its purpose and functionality.

Overall, comments make your scripts more readable, maintainable, and shareable.

How to add comments in PowerShell?

Comments are an essential part of writing PowerShell scripts. To add a comment in PowerShell, use the # (hash symbol) followed by your comment text syntax. Anything on the same line after the “#” symbol will be ignored by the interpreter and will not be executed.

Single Line Comments

The single line comments start with a # hashtag. Anything after the # on that line will be ignored by PowerShell when running the code. Here is the PowerShell single line comments example:

# This is a single line comments
Write-Host "Hello, World!" # This is also a comment

In the above example, “This is a comment” and “This is also a comment” will not be executed, as they are preceded by the “#” symbol. In other words, comments can also be used to disable lines of code in a script temporarily. This can be useful if you want to troubleshoot and test a script without running certain commands. To do this, add a # symbol before the command, which will cause the command to be ignored by the PowerShell interpreter.

For example, if you wanted to skip a cmdlet, you could add the following comment:

# Get-Service -Name MyService # Skip this command.

This allows you to add brief notes on what the code is doing:

# Output Hello World text
Write-Output "Hello World" 

# Display current date 
Get-Date

Comments can be used to explain what a particular line of code does, why it is being used, and how it works. They can also be used to provide instructions or warnings to other users who may be reading or modifying the script.

Multiline Comments in PowerShell

PowerShell also supports multi-line comments, AKA block comments. To add a multi-line comment, you must use the <# and #> tags to mark the start and end of the comment. Any text between the tags is treated as a comment, and the tags themselves are not executed as part of the script. This is useful for longer comments or comments spanning multiple lines of code.

<#
    This is a multi line block comments that can be used to provide more detailed information about a script or function.
    For example, you can use it to explain the purpose of the script, the parameters it accepts, and how it should be used.
#>

Please keep in mind that all the above examples are for comments, PowerShell interpreter will not execute any of the lines that are commented with the above examples.

Multi-line comments are helpful for:

• Describing the overall purpose of a script or function
• Providing instructions and examples for using a script
• Detailing complex logic or algorithms used
• Adding copyright and licensing information

Here is an example of multiple lines of comments (or block comments) in PowerShell:

<#
This is a multi-line comment block
that spans multiple lines.
You can use these for longer descriptions and documentation.
#>

Get-Process

Add comments to parameters in PowerShell

You can add comments to parameters by using the “#” symbol followed by your comment text. For example, if you have a script with a parameter named “FilePath” and you want to add a comment to explain what the parameter does, you would add the following line at the top of your script:

Function Get-FileSize
{
    param(
        # The path to the file to get size
        [parameter(Mandatory=$True)]
        [string]
        $FilePath
    )
    # Get file size in bytes
    $FileSize = (Get-Item -Path $FilePath).Length

    Return [math]::Round($FileSize/1KB,2)
}

#Call the function to get file size
Get-FileSize -FilePath "C:\temp\Applog.zip"

You can use the shortcuts or edit menu to toggle commenting in Visual Studio Code:

Commenting Functions and Parameters for Comment-Based Help

You can comment functions and their parameters like this:

• Document each function and script file purpose at the top with .SYNOPSIS, .DESCRIPTION.
• Use .PARAMETER for each parameter.
• Use .EXAMPLE to show examples.
• Update comments if you modify the function.

<#
.SYNOPSIS
  Get-DiskInventory generates a report of disk space usage.

.DESCRIPTION 
  This script scans all available disk drives and generates an output
  file with a summary of total and free space. It also outputs a 
  break-down of space used by file type.
  
  Output is written to C:\DiskReports\disk-inventory.txt
  
.EXAMPLE
  Get-DiskInventory

.EXAMPLE
  Get-DiskInventory -DriveLetter C:\ D:\

#>

function Get-DiskInventory {

  # Function code goes here

}

Notice that the comment uses .SYNOPSIS, .DESCRIPTION, and .EXAMPLE tags common in PowerShell functions. This allows using Get-Help on the function later to view the formatted comment block.

Get-Help Get-DiskInventory -Full

Comment-based help tags help to document the parameters accepted by your script, expected syntax, and provide illustrative examples.

Insert Function template with comments in PowerShell

Comments allow you to document your code and provide helpful information to other users who may be reading or modifying your scripts. Here is what the function template with the Comments block looks like in PowerShell. This example also shows how to add comments to parameters. This is called comment-based help, when you use the Get-Help cmdlet, these comments will be displayed. Let’s understand it better with the following example:

<#
.Synopsis
   Add Prefix to All files
.DESCRIPTION
   Rename all files in a directory by adding a given prefix to each file name
.EXAMPLE
   Add-PrefixToAllFiles -FolderPath "C:\temp\Docs" -Prefix "Invoice"
.EXAMPLE
   Add-PrefixToAllFiles "C:\temp\Docs" "Invoice"
#>
Function Add-PrefixToAllFiles
{
    [CmdletBinding()]
    Param
    (
        # The path to the Folder where the files are located
        [Parameter(Mandatory=$true,
                   ValueFromPipelineByPropertyName=$true,
                   Position=0)]
        [string]
        $FolderPath,

        # The prefix to be added to the file names        
        [Parameter(Mandatory=$true,
                   ValueFromPipelineByPropertyName=$true,
                   Position=1)]        
        [string]
        $Prefix
    )

    Begin
    {
        # print a message
        Write-Host "Starting renaming of All files in $FolderPath..." -f yellow

    }
    Process
    {
        # Get all files in the specified Folder
        $Files = Get-ChildItem -Path $FolderPath -File

        # Loop through each file and rename it
        ForEach ($File in $Files) {
            $NewName = "$Prefix" + "_" + $File.Name
            Rename-Item -Path $File.FullName -NewName $NewName
        }
    }
    End
    {
        # Confirmation message
        Write-Host "All files in $FolderPath have been renamed with the prefix $Prefix." -f Green
    }
}

#Call the function to rename all files in a directory
Add-PrefixToAllFiles -FolderPath "C:\temp\Docs" -Prefix "Invoice"

In this example, the comments at the top of the script describe the purpose of the script and the parameters that it accepts. The comments inside the script explain the purpose of each block of code. This helps to make the script more readable and easier to understand for others who may need to use or modify it in the future.

You can insert this function block with comments from snippets in Windows PowerShell ISE.

Real-World Examples of Effective Commenting

Here are some real-world examples of effective commenting from my scripts:

1. Commenting Variable Assignments:

$counter = 0  # Initialize a counter variable

2. Documenting Script Purpose:

<#
This script automates the backup of critical system files to a designated external drive.
#>

Backup-SystemFiles -DestinationPath "D:\Backup"

3. Commenting Function Definitions

# Calculates the sum of two numbers
function Add-Numbers {
    param (
        [int]$num1,
        [int]$num2
    )
    
    # Return the sum of the numbers
    return ($num1 + $num2)
}

4. Explaining Complex Logic:

<#
This script modifies the permissions of a specific file.

The current permissions are read-only for all users.

To grant full access to the file, modify the $permissions variable accordingly.

#>

$filePath = "C:\MyFile.txt"
$permissions = Get-Acl -Path $filePath
Set-Acl -Path $filePath -AclObject $permissions -GrantRead -GrantWrite

5. Guiding Future Modifications:

<#
This script identifies and removes duplicate files from a specified directory.

The script utilizes a hash table to store file paths, preventing duplicate entries from being added.
#>

$files = @{}
Get-ChildItem -Path "C:\Backup" | ForEach-Object {
    if (!$files[$_.FullName]) {
        $files[$_.FullName] = $true
    }
    else {
        Remove-Item -Path $_.FullName
    }
}

Best Practices for Using Comments in PowerShell

When creating comments, it’s important to keep them clear and concise. Keep comments short and to the point. Avoid using overly complex language or acronyms that may not be familiar to others. It’s also a good idea to include comments at the beginning of your script to explain what it does and how it works. This will make it easier for others to understand and use your script.

Another good practice is to use comments to explain any complex or tricky code. This will help others understand what is happening and make it easier to maintain your script. It is also best practice to use comments to include information such as the author, date created, and any known issues or limitations of your script. Additionally, it is a good idea to use comments to break up and organize your script into logical sections, making it easier to understand and navigate.

Avoid using unnecessary words or phrases, as this can make the comment difficult to read. Additionally, it is important to be consistent with your comments. For example, if you are using a particular style of commenting in PowerShell, then make sure to use that same style throughout the script. Finally, make sure to use meaningful comments that provide helpful information to other users who may be reading or modifying the script. Use comments to explain why code is doing something, not just what it is doing. Don’t forget to keep them aligned, and make it easy to read.

Conclusion

In conclusion, adding comments to your PowerShell scripts is an important part of writing code, that helps for keeping your code organized, readable, and maintainable. Comments, the unspoken language of PowerShell scripts, serve as invaluable tools for enhancing script clarity, maintainability, and overall quality. They provide explanations, notes, and documentation that make it easier for others to understand and use your script. By keeping your comments clear, concise, and well-organized, you can ensure that your script is easy to understand, maintain, and troubleshoot. By following these tips, you can ensure that your comments are effective and helpful.