Skip to content

Make documentation of AvoidUsingPositionalParameters match the implementation #867

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions RuleDocumentation/AvoidUsingPositionalParameters.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# AvoidUsingPositionalParameters

**Severity Level: Warning**
** Severity Level: Information **

## Description

When developing PowerShell content that will potentially need to be maintained over time, either by the original author or others, you should use full command names and parameter names.

The use of positional parameters can reduce the readability of code and potentially introduce errors.
The use of positional parameters can reduce the readability of code and potentially introduce errors. Furthermore it is possible that future signatures of a Cmdlet could change in a way that would break existing scripts if calls to the Cmdlet rely on the position of the parameters.

For simple Cmdlets with only a few positional parameters, the risk is much smaller and in order for this rule to be not too noisy, this rule gets only triggered when there are 3 or more parameters supplied. A simple example where the risk of using positional parameters is negligible, is e.g. `Test-Path $Path`.

## How

Expand All @@ -17,11 +19,11 @@ Use full parameter names when calling commands.
### Wrong

``` PowerShell
Get-ChildItem *.txt
Get-Command Get-ChildItem Microsoft.PowerShell.Management System.Management.Automation.Cmdlet
```

### Correct

``` PowerShell
Get-Content -Path *.txt
Get-Command -Noun Get-ChildItem -Module Microsoft.PowerShell.Management -ParameterType System.Management.Automation.Cmdlet
```