From 46f7f86be735d1152877aff429c53e6c7a4f558a Mon Sep 17 00:00:00 2001 From: Christoph Bergmeister Date: Sat, 3 Feb 2018 22:43:52 +0000 Subject: [PATCH 1/2] Make documentation of AvoidUsingPositionalParameters match the implementation --- RuleDocumentation/AvoidUsingPositionalParameters.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/RuleDocumentation/AvoidUsingPositionalParameters.md b/RuleDocumentation/AvoidUsingPositionalParameters.md index e1a0de3d4..032ea6fe9 100644 --- a/RuleDocumentation/AvoidUsingPositionalParameters.md +++ b/RuleDocumentation/AvoidUsingPositionalParameters.md @@ -1,6 +1,6 @@ # AvoidUsingPositionalParameters -**Severity Level: Warning** +** Severity Level: Information ** ## Description @@ -8,6 +8,8 @@ When developing PowerShell content that will potentially need to be maintained o The use of positional parameters can reduce the readability of code and potentially introduce errors. +For simple CmdLets with only a few 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. + ## How Use full parameter names when calling commands. @@ -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 ``` From d5e5ee2c398c2c54e995d04535b9049396de30c0 Mon Sep 17 00:00:00 2001 From: Christoph Bergmeister Date: Sun, 4 Feb 2018 19:36:30 +0000 Subject: [PATCH 2/2] add more documentation details as suggested in PR comment --- RuleDocumentation/AvoidUsingPositionalParameters.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/RuleDocumentation/AvoidUsingPositionalParameters.md b/RuleDocumentation/AvoidUsingPositionalParameters.md index 032ea6fe9..fc31c0de7 100644 --- a/RuleDocumentation/AvoidUsingPositionalParameters.md +++ b/RuleDocumentation/AvoidUsingPositionalParameters.md @@ -6,9 +6,9 @@ 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 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. +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