MegaBites-AI/Windows-powershell

1---2applyTo: '**/*.ps1, **/*.psm1'3description: Naming conventions for PowerShell parameters4---5 6# PowerShell Parameter Naming Conventions7 8## Purpose9 10This instruction defines the naming conventions for parameters in PowerShell scripts and modules. Consistent parameter naming improves code readability, maintainability, and usability for users of PowerShell cmdlets and functions.11 12## Parameter Naming Rules13 14### General Conventions15- **Singular Nouns**: Use singular nouns for parameter names even if the parameter is expected to handle multiple values (e.g., `File` instead of `Files`).16- **Use PascalCase**: Parameter names must use PascalCase (e.g., `ParameterName`).17- **Descriptive Names**: Parameter names should be descriptive and convey their purpose clearly (e.g., `FilePath`, `UserName`).18- **Avoid Abbreviations**: Avoid using abbreviations unless they are widely recognized (e.g., `ID` for Identifier).19- **Avoid Reserved Words**: Do not use PowerShell reserved words as parameter names (e.g., `if`, `else`, `function`).20 21### Units and Precision22- **Include Units in Parameter Names**: When a parameter represents a value with units, include the unit in the parameter name for clarity:23  - `TimeoutSec` instead of `Timeout`24  - `RetryIntervalSec` instead of `RetryInterval`25  - `MaxSizeBytes` instead of `MaxSize`26- **Use Full Words for Clarity**: Spell out common terms to match PowerShell conventions:27  - `MaximumRetryCount` instead of `MaxRetries`28  - `MinimumLength` instead of `MinLength`29 30### Alignment with Built-in Cmdlets31- **Follow Existing PowerShell Conventions**: When your parameter serves a similar purpose to a built-in cmdlet parameter, use the same or similar naming:32  - Match `Invoke-WebRequest` parameters when making HTTP requests: `TimeoutSec`, `MaximumRetryCount`, `RetryIntervalSec`33  - Follow common parameter patterns like `Path`, `Force`, `Recurse`, `WhatIf`, `Confirm`34- **Consistency Within Scripts**: If multiple parameters relate to the same concept, use consistent naming patterns (e.g., `TimeoutSec`, `RetryIntervalSec` both use `Sec` suffix).35 36## Examples37 38### Good Parameter Names39```powershell40param(41    [string[]]$File,                    # Singular, even though it accepts arrays42    [int]$TimeoutSec = 30,              # Unit included43    [int]$MaximumRetryCount = 2,        # Full word "Maximum"44    [int]$RetryIntervalSec = 2,         # Consistent with TimeoutSec45    [string]$Path,                      # Standard PowerShell convention46    [switch]$Force                      # Common PowerShell parameter47)48```49 50### Names to Avoid51```powershell52param(53    [string[]]$Files,                   # Should be singular: File54    [int]$Timeout = 30,                 # Missing unit: TimeoutSec55    [int]$MaxRetries = 2,               # Should be: MaximumRetryCount56    [int]$RetryInterval = 2,            # Missing unit: RetryIntervalSec57    [string]$FileLoc,                   # Avoid abbreviations: FilePath58    [int]$Max                           # Ambiguous: MaximumWhat?59)60```61 62## Exceptions63- **Common Terms**: Some common terms may be used in plural form if they are widely accepted in the context (e.g., `Credentials`, `Permissions`).64- **Legacy Code**: Existing code that does not follow these conventions may be exempted to avoid breaking changes, but new code should adhere to these guidelines.65- **Well Established Naming Patterns**: If a naming pattern is well established in the PowerShell community, it may be used even if it does not strictly adhere to these guidelines.66 67## References68- [PowerShell Cmdlet Design Guidelines](https://learn.microsoft.com/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines)69- [About Parameters - PowerShell Documentation](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parameters)70