Add new `about_Comments` document

[surfingoldelephant]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Document new Get-Foo cmdlet" instead of "New cmdlet."

PowerShell Version

5.1, 7.4, 7.5

Summary

I was surprised to find little documentation on PowerShell comments when searching for a document to link a new PS user to.

Aside from the language specification, there doesn't appear to be any formal documentation on comments in general, despite it being an important aspect of PowerShell (or any language). There are documents on specific functionality that utilizes comments, but not comments as a general concept.

I propose creating a new about_Comments document that serves as an overview for PowerShell comments and lists/links to special-cased functionality.

Proposed Content

• Formalize terminology for PowerShell's comment types.

  • The language specification uses "single line comment" and "delimited comment", albeit the latter is not widely recognised.
  • Throughout PowerShell's documentation, comments are inconsistently referred to as (amongst others): "inline comment"/"single comment"/"single line comment"/"single-line comment" and "block comment"/"comment block"/"delimited comment".
  • One possible formalization:
    • "Single-line comment" for # comments.
    • "Block comment" for <# #> comments that span multiple lines.
    • "Single-line block comment" for <# #> comments that start/end on the same line.

• Discuss general use cases for comments and good practices (e.g., comment the "why" of code).

  • Single-line block comments are useful for placeholders or to comment(-out) portions of a line without interrupting the rest of the line. For example:

    # Comment out an element of an array.
    'Foo', <#'Bar', #>'Baz'
    
    # Add a placeholder without breaking code.
    param (
        [string] $P1,
        <# Insert type #> $P2
    )

• Note that block comments cannot be nested. In the example below, Baz is not part of the comment.

  <# 
  Foo
  <# Bar #>
  Baz
  #>

• List functionality that utilizes special-cased comments:

  • Comment-based help
  • #Requires
  • Shebang (#!) on non-Windows platforms
  • # SIG signature block

• List string/token-enclosed comments recognised by PowerShell/.NET:

  • Regex comments ((?#) and #):
    • Supported by all regex-based operations in PowerShell.
    • Includes # comments in -split + IgnorePatternWhitespace's input string.
  • JSON comments (// and /* */):
    • Supported by ConvertFrom-Json and Invoke-RestMethod in PS v6+, but not Test-Json.
  • CSV comments (#):
    • Supported by all CSV cmdlets.
  • # comments in ConvertFrom-StringData's input string.

Proposed Content Type

About Topic

Proposed Title

about_Comments

Related Articles

https://learn.microsoft.com/en-us/powershell/scripting/lang-spec/chapter-02#223-comments
https://learn.microsoft.com/en-us/powershell/scripting/lang-spec/chapter-15#b12-comments
https://devblogs.microsoft.com/powershell/block-comments-in-v2

[sdwheeler]

@surfingoldelephant This is a good idea. Would you be interested in contributing a draft?

[surfingoldelephant]

@surfingoldelephant This is a good idea. Would you be interested in contributing a draft?

Thanks for the consideration.

I am interested; I'll submit a PR with the draft shortly.

[sdwheeler]

I am standardizing how we describe comments in the other articles. In general, the term comment won't be qualified unless we need to distinguish between the formats. This example shows that terminology I want to use.

<#
    This is a block comment.
#>

# This is a single-line comment.

$var = 4 # This is an end-of-line comment

[surfingoldelephant]

That sounds good. What about a <# #> comment that spans a single line? E.g.,

'Foo', <#'Bar', #>'Baz'

[sdwheeler]

That sounds good. What about a <# #> comment that spans a single line? E.g.,

'Foo', <#'Bar', #>'Baz'

That is still a block comment. I suppose it would be an inline block comment.

[surfingoldelephant]

Yes, I was thinking either single-line block comment or inline block comment. I'll use "inline" when there's a need to distinguish it from the typical block comment form.