Do you use Comment-Based Help in PowerShell functions and scripts?

In PowerShell, you can use Comment-Based Help snippets to better define what your function or script is doing, its examples, inputs, and outputs.

When you are building functions in PowerShell, you can use Comment-Based Help snippets at the beginning of the function body, at the end of the function body or before the Function keyword.

If you do this, the Get-Help cmdlet will show the information contained in the code for your function (making it super easy for anyone to use and understand it!).

You can use it like this (beginning of the Function body):

function Get-Function
{
  <#
    .<help keyword>
    <help content>
  #>

  # function logic
}

Figure: Good example - Using Comment-Based Help for Functions

Or like this (before the function keyword):

<#
  .<help keyword>
  <help content>
#>
function Get-Function { }

Figure: Good example - Using Comment-Based Help for Function

You can do the same with scripts, with a little difference - you need to place the snippet at the beginning or end of the script file:

#Accept input parameters
param(
    [switch]$FullAccess,
    [switch]$SendAs,
    [switch]$SendOnBehalf,
    [switch]$UserMailboxOnly,
    [switch]$AdminsOnly,
    [string]$MBNamesFile,
    [string]$UserName,
    [string]$Password,
    [switch]$MFA
)

Figure: Bad example - Script not using any Comment-Based Help snippet

<#
.SYNOPSIS
Gets THE IP addresses in a file and checks if they are on blacklists across the web.

.DESCRIPTION
Gets THE IP addresses in a file and checks if they are on blacklists across the web. If they are, add them to the final blacklist file that will be used by the firewall.

.EXAMPLE
PS C:\> Check-Blacklist -File "FileWithNewIPs" -BaseFile "BaseBlacklistFile" -Logfile "LogfileLocation"
Checks the newly-generated blacklist file to see if any IPs are blacklisted, if yes, adds them to the final blacklist file.

.NOTES
Created by Kiki Biancatti for SSW.

#>
Param(
[Parameter(Position = 0, Mandatory = $true)]
[string] $File,
[Parameter(Position = 1, Mandatory = $true)]
[string] $BaseFile,
[Parameter(Position = 2, Mandatory = $true)]
[string] $LogFile
) ...

Figure: Good example - Using Comment-Based Help at the beginning of a script file

You can check some good PowerShell examples in SSW's GitHub:

Powershell

Do you use Comment-Based Help in PowerShell functions and scripts?

Authors

Categories

Authors

Categories