header
header Register : : Login header
header
divider
menuleft
menuright
submenu
left

PowerShellCommunity is sponsoring this year's Microsoft Technet Scripting Games, along with the new PoshCode.org. Submit your entry today!

This area of the Web site is freely editable by all registered users. When editing, expand the "Directions" item for instructions on creating and linking to new pages. Please help keep this area of the community neat and clean by adding appropriate edits and so forth.
Naming
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:
Keith: I believe Script scope and Global scope variables should use PascalCasing.  This gives me an easy way within some of my larger functions to tell whether a variable is a "local" or a "global".  I also believe this should apply to script params which are essentially global in nature.
 
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:
None
 
 
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:
None
 
 


 |  View Topic History  |
right
   
footer Sponsored by Quest Software • SAPIEN Technologies • Compellent • Microsoft Windows Server 2008 footer
footer