Skip to content

Document the PowerShell output streams and prefer implicit output over return #3

Description

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions