Copilot instructions

1---
2applyTo: '**/*.ps1, **/*.psm1'
3description: Naming conventions for PowerShell parameters
4---
5 
6# PowerShell Parameter Naming Conventions
7 
8## Purpose
9 
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 Rules
13 
14### General Conventions
15- **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 Precision
22- **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 Cmdlets
31- **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## Examples
37 
38### Good Parameter Names
39```powershell
40param(
41    [string[]]$File,                    # Singular, even though it accepts arrays
42    [int]$TimeoutSec = 30,              # Unit included
43    [int]$MaximumRetryCount = 2,        # Full word "Maximum"
44    [int]$RetryIntervalSec = 2,         # Consistent with TimeoutSec
45    [string]$Path,                      # Standard PowerShell convention
46    [switch]$Force                      # Common PowerShell parameter
47)
48```
49 
50### Names to Avoid
51```powershell
52param(
53    [string[]]$Files,                   # Should be singular: File
54    [int]$Timeout = 30,                 # Missing unit: TimeoutSec
55    [int]$MaxRetries = 2,               # Should be: MaximumRetryCount
56    [int]$RetryInterval = 2,            # Missing unit: RetryIntervalSec
57    [string]$FileLoc,                   # Avoid abbreviations: FilePath
58    [int]$Max                           # Ambiguous: MaximumWhat?
59)
60```
61 
62## Exceptions
63- **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## References
68- [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