Problem
The source code test harness does not enforce where parameter documentation lives. Functions can document parameters using .PARAMETER blocks in the comment-based help section at the top of the function, and CI will not catch it. This places the documentation far from the code it describes, which causes drift.
The coding standard (MSXOrg/docs — Functions) requires inline comments directly above each parameter declaration inside param():
param(
# The unique identifier of the user.
[Parameter(Mandatory, Position = 0)]
[ValidateNotNullOrEmpty()]
[string] $UserId,
# Include deleted users in the result.
[Parameter()]
[switch] $IncludeDeleted
).PARAMETER blocks in the comment-based help section are explicitly disallowed — they separate the documentation from the parameter by the entire function header, which causes them to drift out of date as parameters change.
Why inline
- The comment is adjacent to the code it describes — the same reason we keep tests near source and config near the component it configures.
- A diff that changes a parameter and its inline comment is one coherent hunk; a diff that changes a parameter and a
.PARAMETER block is two separate hunks that are easy to keep in sync badly.
Get-Help renders inline comments identically to .PARAMETER blocks, so there is no user-facing cost.
What to add
Add Pester tests to SourceCode/PSModule/PSModule.Tests.ps1 for every function file (public and private):
1. No .PARAMETER blocks in comment-based help
- Parse the comment-based help block (AST or regex on the raw
<# ... #> content).
- Fail if any
.PARAMETER keyword is found inside the comment-based help block.
2. Every parameter has an inline comment
- Parse the
param() block via AST ([System.Management.Automation.Language.Parser]::ParseFile).
- For each
ParameterAst, check that the token immediately preceding the first attribute or type on that parameter is a single-line comment (# ...).
- Fail if any parameter is missing its inline comment.
3. Skip mechanism
Follow the existing pattern: #SkipTest:ParameterCommentPlacement:<Reason> suppresses the check for the whole file with a warning.
Acceptance criteria
Related
Problem
The source code test harness does not enforce where parameter documentation lives. Functions can document parameters using
.PARAMETERblocks in the comment-based help section at the top of the function, and CI will not catch it. This places the documentation far from the code it describes, which causes drift.The coding standard (MSXOrg/docs — Functions) requires inline comments directly above each parameter declaration inside
param():.PARAMETERblocks in the comment-based help section are explicitly disallowed — they separate the documentation from the parameter by the entire function header, which causes them to drift out of date as parameters change.Why inline
.PARAMETERblock is two separate hunks that are easy to keep in sync badly.Get-Helprenders inline comments identically to.PARAMETERblocks, so there is no user-facing cost.What to add
Add Pester tests to
SourceCode/PSModule/PSModule.Tests.ps1for every function file (public and private):1. No
.PARAMETERblocks in comment-based help<# ... #>content)..PARAMETERkeyword is found inside the comment-based help block.2. Every parameter has an inline comment
param()block via AST ([System.Management.Automation.Language.Parser]::ParseFile).ParameterAst, check that the token immediately preceding the first attribute or type on that parameter is a single-line comment (# ...).3. Skip mechanism
Follow the existing pattern:
#SkipTest:ParameterCommentPlacement:<Reason>suppresses the check for the whole file with a warning.Acceptance criteria
.PARAMETERblock causes a test failure..PARAMETERblock passes.#SkipTest:ParameterCommentPlacement:<Reason>suppresses the check and emits a warning.Related
.INPUTS/.OUTPUTSformat validation (same test file, same pattern).INPUTSand.OUTPUTSformat rules added to PowerShell function help standards MSXOrg/docs#65 — coding standard that documents this convention