Context
index.md says "emit objects, not formatted text" and reserves Write-Host for genuine console UX, with Write-Verbose / Write-Information for narration. Functions.md covers throw vs Write-Error.
Gap
We do not give the full output-stream taxonomy, nor the "don't use return to emit" idiom:
- Implicit output for results — prefer placing the object on its own line over
return $obj; in a pipeline function, emit from the process block, not end.
Write-Verbose for status and why-a-path-was-chosen (useful, not necessary).
Write-Progress for progress (ephemeral — never the only place information the user needs appears).
Write-Debug for maintainer breadcrumbs.
Write-Warning and Write-Error for warnings and non-terminating errors.
Write-Host only for Show- / Format- verbs or interactive prompts.
[CmdletBinding()] is what enables the -Verbose / -Debug switches that turn those streams on.
Proposed change
Add an "Output streams" subsection to Functions.md (or the index.md idioms) with a stream-per-purpose list, and add "prefer implicit output over return" to the Functions output rules.
Source
PoshCode — Best Practices "Output and Formatting"; Style Guide "Function Structure".
Acceptance
The standard lists each output stream with its purpose, restricts Write-Host, and states the implicit-output-over-return rule.
Context
index.mdsays "emit objects, not formatted text" and reservesWrite-Hostfor genuine console UX, withWrite-Verbose/Write-Informationfor narration.Functions.mdcoversthrowvsWrite-Error.Gap
We do not give the full output-stream taxonomy, nor the "don't use
returnto emit" idiom:return $obj; in a pipeline function, emit from theprocessblock, notend.Write-Verbosefor status and why-a-path-was-chosen (useful, not necessary).Write-Progressfor progress (ephemeral — never the only place information the user needs appears).Write-Debugfor maintainer breadcrumbs.Write-WarningandWrite-Errorfor warnings and non-terminating errors.Write-Hostonly forShow-/Format-verbs or interactive prompts.[CmdletBinding()]is what enables the-Verbose/-Debugswitches that turn those streams on.Proposed change
Add an "Output streams" subsection to
Functions.md(or theindex.mdidioms) with a stream-per-purpose list, and add "prefer implicit output overreturn" to the Functions output rules.Source
PoshCode — Best Practices "Output and Formatting"; Style Guide "Function Structure".
Acceptance
The standard lists each output stream with its purpose, restricts
Write-Host, and states the implicit-output-over-returnrule.