Skip to content

Commit f98ace1

Browse files
Apply suggestions from code review
1 parent e0954a4 commit f98ace1

File tree

4 files changed

+94
-93
lines changed

4 files changed

+94
-93
lines changed

reference/docs-conceptual/PSScriptAnalyzer/create-custom-rule.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ Param
5353
)
5454
```
5555

56-
The name of the _Token_ parameter name must end with **Token**.
56+
The name of the **Token** parameter name must end with **Token**.
5757

5858
```powershell
5959
Param
@@ -67,12 +67,12 @@ Param
6767

6868
### DiagnosticRecord should have the required properties
6969

70-
The `DiagnosticRecord` should have at least four properties:
70+
The **DiagnosticRecord** should have at least four properties:
7171

72-
- Message
73-
- Extent
74-
- RuleName
75-
- Severity
72+
- **Message**
73+
- **Extent**
74+
- **RuleName**
75+
- **Severity**
7676

7777
```powershell
7878
$result = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]]@{
@@ -84,7 +84,7 @@ $result = [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[
8484
```
8585

8686
Since version 1.17.0, you can include a **SuggestedCorrections** property of type
87-
`IEnumerable<CorrectionExtent>`. Care must be taken that the type is correct. For example:
87+
**IEnumerable\<CorrectionExtent\>**. Make sure to specify the correct type. For example:
8888

8989
```powershell
9090
[int]$startLineNumber = $ast.Extent.StartLineNumber

reference/docs-conceptual/PSScriptAnalyzer/overview.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ best practices identified by PowerShell Team and the community. It generates **D
1111
(errors and warnings) to inform users about potential code defects and suggests possible solutions
1212
for improvements.
1313

14-
PSScriptAnalyzer is shipped with a collection of built-in rules that check various aspects of
14+
PSScriptAnalyzer ships with a collection of built-in rules that check various aspects of
1515
PowerShell code such as:
1616

1717
- The presence of uninitialized variables
@@ -28,7 +28,7 @@ standard style, is easier to read, and is more maintainable.
2828
Supported PowerShell Versions and Platforms
2929

3030
- Windows PowerShell 3.0 or greater
31-
- PowerShell Core 7.0.3 or greater on Windows/Linux/macOS
31+
- PowerShell 7.0.3 or greater on Windows/Linux/macOS
3232

3333
Install using PowerShellGet 2.x:
3434

@@ -43,4 +43,5 @@ Install-PSResource -Name PSScriptAnalyzer -Reinstall
4343
```
4444

4545
The **Force** or **Reinstall** parameters are only necessary when you have an older version of
46-
PSScriptAnalyzer installed. However, these parameters work whether you have a previous version or not.
46+
PSScriptAnalyzer installed. These parameters also work even when you do not have a previous version
47+
installed.

reference/docs-conceptual/PSScriptAnalyzer/rules-recommendations.md

Lines changed: 41 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ title: PSScriptAnalyzer rules and recommendations
77

88
The following guidelines come from a combined effort from both the PowerShell team and the
99
community. The guidelines are organized by type. Within each type there is a list of rules. The
10-
rules are grouped by the **Severity** defined in the implementation of the **PSScriptAnalyzer** rule.
11-
The severity level labeled as 'TBD' means "To be determined". These are recommendations that do not
12-
currently have rules defined.
10+
rules are grouped by the **Severity** defined in the implementation of the **PSScriptAnalyzer**
11+
rule. The severity level labeled as 'TBD' means "To be determined". These are recommendations that
12+
do not currently have rules defined.
1313

1414
## Cmdlet Design Rules
1515

@@ -19,25 +19,25 @@ No rules defined.
1919

2020
### Severity: Warning
2121

22-
- Use Only Approved Verbs [UseApprovedVerbs](Rules/UseApprovedVerbs.md)
23-
- Cmdlets Names: Characters that cannot be Used
22+
- Use only Approved Verbs [UseApprovedVerbs](Rules/UseApprovedVerbs.md)
23+
- Cmdlets names with unusable characters
2424
[AvoidReservedCharInCmdlet](Rules/ReservedCmdletChar.md)
25-
- Parameter Names that cannot be Used
25+
- Parameter names that cannot be used
2626
[AvoidReservedParams](Rules/ReservedParams.md)
27-
- Support Confirmation Requests
27+
- Support confirmation requests
2828
[UseShouldProcessForStateChangingFunctions](Rules/UseShouldProcessForStateChangingFunctions.md)
2929
and
3030
[UseShouldProcessForStateChangingFunctions](Rules/UseShouldProcessForStateChangingFunctions.md)
31-
- Must call ShouldProcess when ShouldProcess attribute is present and vice
32-
versa.[UseShouldProcess](Rules/ShouldProcess.md)
31+
- Must call **ShouldProcess** when the **ShouldProcess** attribute is present and vice
32+
versa [UseShouldProcess](Rules/ShouldProcess.md)
3333
- Nouns should be singular
3434
[UseSingularNouns](Rules/UseSingularNouns.md)
35-
- Module Manifest Fields
35+
- Missing module manifest fields
3636
[MissingModuleManifestField](Rules/MissingModuleManifestField.md)
37-
- Version
38-
- Author
39-
- Description
40-
- LicenseUri (for PowerShell Gallery)
37+
- **Version**
38+
- **Author**
39+
- **Description**
40+
- **LicenseUri** (for PowerShell Gallery)
4141
- Switch parameters should not default to true
4242
[AvoidDefaultValueSwitchParameter](Rules/AvoidDefaultValueSwitchParameter.md)
4343

@@ -70,24 +70,23 @@ No rules defined.
7070

7171
### Severity: Warning
7272

73-
- Avoid using alias
73+
- Avoid using aliases
7474
[AvoidUsingCmdletAliases](Rules/AvoidUsingCmdletAliases.md)
7575
- Avoid using deprecated WMI cmdlets
7676
[AvoidUsingWMICmdlet](Rules/AvoidUsingWMICmdlet.md)
77-
- Empty catch block should not be used
78-
[AvoidUsingEmptyCatchBlock](Rules/AvoidUsingEmptyCatchBlock.md)
79-
- Invoke existing cmdlet with correct parameters
77+
- Avoid using empty **catch** blocks [AvoidUsingEmptyCatchBlock](Rules/AvoidUsingEmptyCatchBlock.md)
78+
- Invoke existing cmdlets with correct parameters
8079
[UseCmdletCorrectly](Rules/UseCmdletCorrectly.md)
81-
- Cmdlets should have ShouldProcess/ShouldContinue and Force param if certain system-modding verbs
82-
are present (Update, Set, Remove, New):
80+
- Cmdlets should have **ShouldProcess**/**ShouldContinue** and **Force** parameter if using certain
81+
system-modifying verbs (Update, Set, Remove, New):
8382
[UseShouldProcessForStateChangingFunctions](Rules/UseShouldProcessForStateChangingFunctions.md)
84-
- Positional parameters should be avoided
83+
- Avoid using positional parameters
8584
[AvoidUsingPositionalParameters](Rules/AvoidUsingPositionalParameters.md)
86-
- Global variables should be avoided.
85+
- Avoid using global variables
8786
[AvoidGlobalVars](Rules/AvoidGlobalVars.md)
88-
- Declared variables must be used in more than just their assignment.
87+
- Declared variables should be used after their assignment
8988
[UseDeclaredVarsMoreThanAssignments](Rules/UseDeclaredVarsMoreThanAssignments.md)
90-
- No Invoke-Expression
89+
- Avoid using `Invoke-Expression`
9190
[AvoidUsingInvokeExpression](Rules/AvoidUsingInvokeExpression.md)
9291

9392
### Severity: Information
@@ -96,11 +95,11 @@ No rules defined.
9695

9796
### Severity: TBD
9897

99-
- `Clear-Host` should not be used
100-
- File paths should not be used (UNC)
98+
- Avoid using `Clear-Host`
99+
- Avoid using UNC file paths
101100
- Error Handling
102101
- Use `-ErrorAction Stop` when calling cmdlets
103-
- Use $ErrorActionPreference = 'Stop'/' Continue' when calling non-cmdlets
102+
- Use `$ErrorActionPreference = 'Stop'/'Continue'` when calling non-cmdlets
104103
- Avoid using flags to handle errors
105104
- Avoid using `$?`
106105
- Avoid testing for a null variable as an error condition
@@ -117,7 +116,7 @@ No rules defined.
117116

118117
### Severity: Warning
119118

120-
- Don't use `Write-Host` unless writing to the host is all you want to do
119+
- Avoid using `Write-Host` unless writing to the host is all you want to do
121120
[AvoidUsingWriteHost](Rules/AvoidUsingWriteHost.md)
122121

123122
### Severity: Information
@@ -129,7 +128,7 @@ No rules defined.
129128

130129
- Provide usage Examples
131130
- Use the Notes section for details on how the tool works
132-
- Should have help on every exported command (including parameter documentation)
131+
- Every exported command should have help (including parameter documentation)
133132
- Document the version of PowerShell that the script was written for
134133
- Indent your code
135134
- Avoid backticks
@@ -138,18 +137,18 @@ No rules defined.
138137

139138
### Severity: Error
140139

141-
- Password should be secure string
140+
- Avoid using plain text passwords
142141
[AvoidUsingPlainTextForPassword](Rules/AvoidUsingPlainTextForPassword.md)
143-
- Should never have both `-Username` and `-Password` parameters (should take credentials):
142+
- Avoid `-Username` and `-Password` parameters (use **PSCredential** instead):
144143
[UsePSCredentialType](Rules/UsePSCredentialType.md)
145-
- `-ComputerName` Parameter argument hardcoded should not be used (information disclosure):
144+
- Avoid hardcoding a `-ComputerName` parameter argument (information disclosure):
146145
[AvoidUsingComputerNameHardcoded](Rules/AvoidUsingComputerNameHardcoded.md)
147-
- ConvertTo-SecureString with plaintext should not be used (information disclosure):
146+
- Avoid using `ConvertTo-SecureString` with plaintext (information disclosure):
148147
[AvoidUsingConvertToSecureStringWithPlainText](Rules/AvoidUsingConvertToSecureStringWithPlainText.md)
149148

150149
### Severity: Warning
151150

152-
- Information disclosure - `$Password = 'string'` should not be used.
151+
- Avoid using `$Password = 'string'` (information disclosure).
153152
[AvoidUsingUsernameAndPasswordParams](Rules/AvoidUsingUsernameAndPasswordParams.md)
154153

155154
### Severity: Information
@@ -158,7 +157,7 @@ No rules defined.
158157

159158
### Severity: TBD
160159

161-
- APIKey and Credentials variables that are initialized (information disclosure)
160+
- Avoid initializing APIKey and Credentials variables (information disclosure)
162161

163162
## DSC Related Rules
164163

@@ -180,19 +179,20 @@ No rules defined.
180179
- The following three recommendations are covered by the
181180
[ReturnCorrectTypesForDSCFunctions](Rules/DSCReturnCorrectTypesForDSCFunctions.md) rule
182181
- Avoid returning any object from a `Set-TargetResource` or Set (Class Based) function
183-
- Returning a Boolean object from a `Test-TargetResource` or Test (Class Based) function
184-
- Returning an object from a `Get-TargetResource` or Get (Class Based) function
182+
- Return a Boolean value from a `Test-TargetResource` or Test (Class Based) function
183+
- Return an object from a `Get-TargetResource` or Get (Class Based) function
185184
- DSC resources should have DSC tests [DSCTestsPresent](Rules/DSCDscTestsPresent.md)
186185
- DSC resources should have DSC examples [DSCExamplesPresent](Rules/DSCDscExamplesPresent.md)
187186

188187
### Severity: TBD
189188

190-
- For PowerShell V4, Resource module contains `.psd1` file and `schema.mof` for every resource
191-
- MOF has description for each element - see
189+
- For Windows PowerShell v4, resource modules should have a `.psd1` file and `schema.mof` for every
190+
resource
191+
- MOFs should have a description for each element - see
192192
[Issue #131](https://github.com/PowerShell/PSScriptAnalyzer/issues/131)
193-
- Resource module must contain .psd1 file (always) and schema.mof (for non-class resource) - see
193+
- Resource modules should have a `.psd1` file (always) and `schema.mof` (for non-class resource) see
194194
[Issue #116](https://github.com/PowerShell/PSScriptAnalyzer/issues/116)
195-
- Use ShouldProcess for a Set DSC method
195+
- Use **ShouldProcess** for a **Set** DSC method
196196
- Resource module contains DscResources folder which contains the resources - see
197197
[Issue #130](https://github.com/PowerShell/PSScriptAnalyzer/issues/130)
198198

0 commit comments

Comments
 (0)