|
|
|
History for
Naming
(history as of 11/9/2007 1:30:06 PM)
Name: ScriptAndGlobalFunctionNamesShouldFollowCmdletNamingStandards
Short Description: Script (and global function) names should follow the Verb-Noun cmdlet naming guidelines.
Long Description:
Since scripts and global functions act just like cmdlets, they should be just as easy to use. One of the main benefits of PowerShell is its regular verb / noun naming syntax, which promotes consistency and commands that are easy to discover. Name scripts (and global functions) with a Verb followed by a dash (-) followed by a Noun.
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
None
Name: VerbsShouldBeSelectedFromStandardList
Short Description: Verbs in script (and global function) names should be selected from the list of standard verbs.
Long Description:
One goal of PowerShell is to let administrators manage 80% of their system with the standard verbs. This makes it easier for an administrator to learn the actions available for a new noun (such as Service or Process,) since they already know the verbs that map to common actions.
The following script gives all of the standard Verb names:
$assembly = [System.Reflection.Assembly]::LoadWithPartialName("System.Management.Automation")
$types = $assembly.GetTypes() | ? { $_.Name -like "Verbs*" }
$types | % { $_.GetFields() | % { $_.Name } } | Sort
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
None
Name: ScriptAndGlobalFunctionNamesShouldBePascalCased
Short Description: Script (and global function) names should be pascal cased.
Long Description:
Script and global names should be pascal cased. For example: Get-ChildItem, Stop-Process. This provides consistency with existing PowerShell cmdlets.
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
None
Name: CamelCaseVariableNames
Short Description: Apply camelCasing to variable names.
Long Description:
Camel casing describes a variable capitalization convention that requires the first letter of the variable name to be lowercase, with an uppercase letter indicating the start of any joined words. For example, documentLibrary, siteConnection, isCurrentlyConnected.
In the .NET style guidelines, identifier names that start with a capital letter indicate publicly-exposed information -- such as the handle count property of $process.HandleCount. This is called PascalCasing. Conversely, identifier names that start with a lower case letter indicate internal information.
The interaction with (and transition to) .NET languages is very common with PowerShell scripters. Since this is suggested by the .NET guidelines, PowerShell scripting follows this guidance.
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
Name: NounNamesShouldBeSpecific
Short Description: Noun names should be specific.
Long Description:
While it may be convenient to use "Project" or "Server" as the noun for your script or global function, common nouns will collide with others that have also chosen that noun. Colliding nouns mean that your users will need to rename your script before they can use it. PowerShell uses the "Ps" prefix for its common nouns, and script authors should apply a similar naming convention.
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
None
Name: NounNamesShouldBeSingular
Short Description: Noun names should be singular.
Long Description:
Noun names should be singular, as noun pluralization is a grammatical minefield -- for English and non-English users alike. You append an 's' to some nouns, an 'es' to some others, or change the noun entirely for others still (as in the case of mouse.) In addition, commands are inconsistent in their support for multiple return values. Get-Date and Get-Location are two examples of cmdlets that can not return muliple values, while Get-Process and Get-Service can. Users should not have to decide the name of a command based on guesses of implementation details.
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
None
Name: ScriptsIntendedToBeDotSourcedShouldUseLibraryPrefix
Short Description: Scripts that define persistent functions and variables (with the intention of dot sourcing) should start with a prefix of "Library."
Long Description:
A "Library" prefix (such as "LibraryTime.ps1") provides a quick way to distinguish between which scripts can be invoked as commands (Verb-Noun,) and which scripts should be dot-sourced. In addition, providing this indicator as a prefix (as opposed to suffix) gives a natural grouping when the user sorts files by name.
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
None
Name: ProvideDescriptiveVariableNames
Short Description: Provide descriptive variable names to clearly identify their purpose.
Long Description:
Descriptive variable names are one of the easiest ways to ensure readability of your code. Rather than define obtuse shortcuts such as $obj, $var, $tmp and $l, define variable names that clearly identify their purpose:
- for($counter = 0; $counter -lt 10; $counter++)
- $connectionString = "..."
- foreach($serverName in $servers) { ... }
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
Name: AvoidHungarianNotation
Short Description: Avoid hungarian notation in scripts.
Long Description:
Hungarian notation describes a variable naming convention that prefixes variable names with their data type, and often scope. This is usually only helpful when the exact prefixes for data types and other identifiers is standardized across large code bases. In addition, everybody reading or writing the source code must be trained to understand and follow these defined standards. These conditions are unlikely to hold true in scripts that you share with others, and will instead make variable names much less readable.
Source / References:
PowerShell Team Guidance
Status: Accepted
Discussion / Open Issues:
|<< Back |
|