|
| 1 | +--- |
| 2 | +applyTo: |
| 3 | + - "**/*.ps1" |
| 4 | + - "**/*.psm1" |
| 5 | +--- |
| 6 | + |
| 7 | +# PowerShell Automatic Variables - Naming Guidelines |
| 8 | + |
| 9 | +## Purpose |
| 10 | + |
| 11 | +This instruction provides guidelines for avoiding conflicts with PowerShell's automatic variables when writing PowerShell scripts and modules. |
| 12 | + |
| 13 | +## What Are Automatic Variables? |
| 14 | + |
| 15 | +PowerShell has built-in automatic variables that are created and maintained by PowerShell itself. Assigning values to these variables can cause unexpected behavior and side effects. |
| 16 | + |
| 17 | +## Common Automatic Variables to Avoid |
| 18 | + |
| 19 | +### Critical Variables (Never Use) |
| 20 | + |
| 21 | +- **`$matches`** - Contains the results of regular expression matches. Overwriting this can break regex operations. |
| 22 | +- **`$_`** - Represents the current object in the pipeline. Only use within pipeline blocks. |
| 23 | +- **`$PSItem`** - Alias for `$_`. Same rules apply. |
| 24 | +- **`$args`** - Contains an array of undeclared parameters. Don't use as a regular variable. |
| 25 | +- **`$input`** - Contains an enumerator of all input passed to a function. Don't reassign. |
| 26 | +- **`$LastExitCode`** - Exit code of the last native command. Don't overwrite unless intentional. |
| 27 | +- **`$?`** - Success status of the last command. Don't use as a variable name. |
| 28 | +- **`$$`** - Last token in the last line received by the session. Don't use. |
| 29 | +- **`$^`** - First token in the last line received by the session. Don't use. |
| 30 | + |
| 31 | +### Context Variables (Use with Caution) |
| 32 | + |
| 33 | +- **`$Error`** - Array of error objects. Don't replace, but can modify (e.g., `$Error.Clear()`). |
| 34 | +- **`$PSBoundParameters`** - Parameters passed to the current function. Read-only. |
| 35 | +- **`$MyInvocation`** - Information about the current command. Read-only. |
| 36 | +- **`$PSCmdlet`** - Cmdlet object for advanced functions. Read-only. |
| 37 | + |
| 38 | +### Other Common Automatic Variables |
| 39 | + |
| 40 | +- `$true`, `$false`, `$null` - Boolean and null constants |
| 41 | +- `$HOME`, `$PSHome`, `$PWD` - Path-related variables |
| 42 | +- `$PID` - Process ID of the current PowerShell session |
| 43 | +- `$Host` - Host application object |
| 44 | +- `$PSVersionTable` - PowerShell version information |
| 45 | + |
| 46 | +For a complete list, see: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables |
| 47 | + |
| 48 | +## Best Practices |
| 49 | + |
| 50 | +### ❌ Bad - Using Automatic Variable Names |
| 51 | + |
| 52 | +```powershell |
| 53 | +# Bad: $matches is an automatic variable used for regex capture groups |
| 54 | +$matches = Select-String -Path $file -Pattern $pattern |
| 55 | +
|
| 56 | +# Bad: $args is an automatic variable for undeclared parameters |
| 57 | +$args = Get-ChildItem |
| 58 | +
|
| 59 | +# Bad: $input is an automatic variable for pipeline input |
| 60 | +$input = Read-Host "Enter value" |
| 61 | +``` |
| 62 | + |
| 63 | +### ✅ Good - Using Descriptive Alternative Names |
| 64 | + |
| 65 | +```powershell |
| 66 | +# Good: Use descriptive names that avoid conflicts |
| 67 | +$matchedLines = Select-String -Path $file -Pattern $pattern |
| 68 | +
|
| 69 | +# Good: Use specific names for arguments |
| 70 | +$arguments = Get-ChildItem |
| 71 | +
|
| 72 | +# Good: Use specific names for user input |
| 73 | +$userInput = Read-Host "Enter value" |
| 74 | +``` |
| 75 | + |
| 76 | +## Naming Alternatives |
| 77 | + |
| 78 | +When you encounter a situation where you might use an automatic variable name, use these alternatives: |
| 79 | + |
| 80 | +| Avoid | Use Instead | |
| 81 | +|-------|-------------| |
| 82 | +| `$matches` | `$matchedLines`, `$matchResults`, `$regexMatches` | |
| 83 | +| `$args` | `$arguments`, `$parameters`, `$commandArgs` | |
| 84 | +| `$input` | `$userInput`, `$inputValue`, `$inputData` | |
| 85 | +| `$_` (outside pipeline) | Use a named parameter or explicit variable | |
| 86 | +| `$Error` (reassignment) | Don't reassign; use `$Error.Clear()` if needed | |
| 87 | + |
| 88 | +## How to Check |
| 89 | + |
| 90 | +### PSScriptAnalyzer Rule |
| 91 | + |
| 92 | +PSScriptAnalyzer has a built-in rule that detects assignments to automatic variables: |
| 93 | + |
| 94 | +```powershell |
| 95 | +# This will trigger PSAvoidAssignmentToAutomaticVariable |
| 96 | +$matches = Get-Something |
| 97 | +``` |
| 98 | + |
| 99 | +**Rule ID**: PSAvoidAssignmentToAutomaticVariable |
| 100 | + |
| 101 | +### Manual Review |
| 102 | + |
| 103 | +When writing PowerShell code, always: |
| 104 | +1. Avoid variable names that match PowerShell keywords or automatic variables |
| 105 | +2. Use descriptive, specific names that clearly indicate the variable's purpose |
| 106 | +3. Run PSScriptAnalyzer on your code before committing |
| 107 | +4. Review code for variable naming during PR reviews |
| 108 | + |
| 109 | +## Examples from the Codebase |
| 110 | + |
| 111 | +### Example 1: Regex Matching |
| 112 | + |
| 113 | +```powershell |
| 114 | +# ❌ Bad - Overwrites automatic $matches variable |
| 115 | +$matches = [regex]::Matches($content, $pattern) |
| 116 | +
|
| 117 | +# ✅ Good - Uses descriptive name |
| 118 | +$regexMatches = [regex]::Matches($content, $pattern) |
| 119 | +``` |
| 120 | + |
| 121 | +### Example 2: Select-String Results |
| 122 | + |
| 123 | +```powershell |
| 124 | +# ❌ Bad - Conflicts with automatic $matches |
| 125 | +$matches = Select-String -Path $file -Pattern $pattern |
| 126 | +
|
| 127 | +# ✅ Good - Clear and specific |
| 128 | +$matchedLines = Select-String -Path $file -Pattern $pattern |
| 129 | +``` |
| 130 | + |
| 131 | +### Example 3: Collecting Arguments |
| 132 | + |
| 133 | +```powershell |
| 134 | +# ❌ Bad - Conflicts with automatic $args |
| 135 | +function Process-Items { |
| 136 | + $args = $MyItems |
| 137 | + # ... process items |
| 138 | +} |
| 139 | +
|
| 140 | +# ✅ Good - Descriptive parameter name |
| 141 | +function Process-Items { |
| 142 | + [CmdletBinding()] |
| 143 | + param( |
| 144 | + [Parameter(ValueFromRemainingArguments)] |
| 145 | + [string[]]$Items |
| 146 | + ) |
| 147 | + # ... process items |
| 148 | +} |
| 149 | +``` |
| 150 | + |
| 151 | +## References |
| 152 | + |
| 153 | +- [PowerShell Automatic Variables Documentation](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables) |
| 154 | +- [PSScriptAnalyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/README.md) |
| 155 | +- [PowerShell Best Practices](https://learn.microsoft.com/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines) |
| 156 | + |
| 157 | +## Summary |
| 158 | + |
| 159 | +**Key Takeaway**: Always use descriptive, specific variable names that clearly indicate their purpose and avoid conflicts with PowerShell's automatic variables. When in doubt, choose a longer, more descriptive name over a short one that might conflict. |
0 commit comments