How-to: # PowerShell comment

In PowerShell single line comments start with a hash symbol, everything to the right of the # will be ignored.

# comment

In PowerShell 2.0 and above multi-line block comments can be used:

<# comment
contines #>

Multi-line comments are typically used to add descriptive help at the start of a script, but also work to embed comment text within a command.

Comment-based Help was also added in PS 2.0, this allows the addition of some standardised tags to a scripts comments which allow the Script to interact with Get-Help.
See this template script, or read Help about_Comment_Based_Help for a full list of .Keywords.

Examples

Copy-Item demo.msi C:\install\demo.msi #copy the installer

<#
   This script will talk to you in french
   language function based on: www.example.com/powershell.html
   Last updated: 1666-09-02
#>

Get-Content -Path <#configuration file#> C:\install\app64.ini

By using embedded comments you can document the arguments for a cmdlet:

PS C:\> Get-ChildItem    <# list the items               #> `
    -Path   $env:windir  <# of the Windows system folder #> `
    -Filter *.dll        <# that are DLLs                #> `
    -Recurse             <# and search all subfolders    #>

Comment based help

Comment-based help topics can be added to functions and scripts. This is done using special help comment keywords that start with a period. Examples of these are below, you can add as many or as few of these to your script as needed to provide the relevant level of detailed help.

<#
.SYNOPSIS
    This script/function does - What?

.DESCRIPTION
    A more detailed description of why and how the function works.

.PARAMETER DemoParam1
    The parameter DemoParam1 is used to define the value of blah and also blah.

.PARAMETER DemoParam2
    The parameter DemoParam2 is used to define the value of blah and also blah.

.EXAMPLE
    The example below does blah
    PS C:\> Example

.EXAMPLE
    Another example

.NOTES
    Author: Name
    Last Edit: yyyy-mm-dd
    Version 1.0 - initial release of blah
    Version 1.1 - update for blah

#>

To display this help text, use Get-Help
e.g.
get-help ./script.ps1
get-help myfunction (this will only work once the function has been loaded/Dot sourced)

Where to add the Comment-based help:

Comment-based help for a script must appear at the beginning of the script (it can also be placed at the end of the script file but only if the script is not signed.)

Comment-based help for a function can appear in one of three locations:

Most people put all comments at the beginning of the script/function.

Default Help

If you call get-help for a script that does not have any comment based help but does have parameters defined with a PARAM ( ) statement, then get-help will return those parameter details.

It is also possible to get a slightly more verbose set of default help text by including just <# .SYNOPSIS #> at the top of the script.

See Help about_Comment_Based_Help for more.

Copy and Paste

Because PowerShell supports Tab Completion you need to be careful about copying and pasting Space + TAB characters (particularly just before the # comment delimiter).

Example:

Function demo() {
} # comment

^ That line is }<space><tab> #
when copied/pasted onto the PowerShell command line, this happens:

PS C:\batch> Function demo() {
>> } .\aaardvaark.cmd# comment
>>
The term '.\aaardvaark.cmd#' is not recognized as the name of a cmdlet, function, script file...


What is happening is that the space-tab gets expanded to match the first file in the current directory, in this case aaardvaark.cmd. If the sequence had been <space><tab><space> and the first file had been a PowerShell script or an executable then it would actually be run.

If the white space consists of nothing but <space> characters (or nothing but <tab> characters) then this will never occur.

#Now stand in the place where you work, Now face West
Think about the place where you live, Wonder why you haven’t before# - REM 'Stand'

Related PowerShell Cmdlets

Escape characters - double \\ to escape them


 
Copyright © 1999-2024 SS64.com
Some rights reserved