PowerShell Security (PoshSec) Style Guidelines and Best Practices

Style Guidelines

Below are style guidelines for working with code in the Poshsec (PowerShell Security) project. If you have suggestions or revisions you would like to make to the Guidelines please run them by the project manager and/or lead developer before updating the document.

Aliases

If you provide aliases for a given function place the alias definition immediate after the function definition. By default all aliases are exported with the module.

Functions

When adding code to functions follow these keys:
*Place opening and closing brackets on a new line.
*Any help should be placed immediately after the opening bracket. At the very least include a synposis, a description, at least one example, all parameters, input and output types. Note are appreciated but not necessary to help clarify any specific issues end users may need to be alerted to with a given function.
*Unless you have a compelling reason, add CmdletBinding() to all functions.
*If using a default parameter set include the name in the CmdletBinding() attribute block.
*Place param() blocks immediately after the CmdletBinding() attribute.
*Utilize Parameter() attributes to handle positional naming, mandatory parameters, parameter set names, etc. Place attributes in alphabetical order.
*Add as much validation in the parameter definition as possible. This includes ValidateScript() and other validation attributes.
*Include a data type for all variables.
*ariables are to be capitalized in param blocks. Start with first letter capitalization and capitalize each main word in a variable name.
*Add an #end function tag along with the function name.
Below is an example of a properly styled function:

function Test-Port
{
[CmdletBinding()]
param(
[Parameter(
Mandatory = $true,
Position = 0,
ValueFromPipeline = $true
)]
[String[]]
$Hostname
)
# Code here
}

Indention

Indenting helps keep a clear line of organization and logic for PowerShell code. Indent 1 tab (or 4 spaces) when:
*adding new code inside a region
*adding code to a function
*adding

Regions

To organize code we use the #region/#endregion conventions from Visual Studio. Most PowerShell IDE’s allow code collapsing and these tags make it easy to skip large code segments. When adding regions include a descriptive tag to the opening and closing tag to help identify where a region begins and end. For example, here is a tag set for the the Audit region:

#region Audit

#endregion Audit

When beginning a nested region indent the new region. For example, if you had a subsection, Web servers, in the Audit region, it would look like this:

#region Audit

#region Web servers

# Code goes here

#endregion Web servers

#endregion Audit

Best Practices

In testing functions, do not use Test-Connection to ensure a remote machine is accessible.

Last edited Oct 14, 2012 at 12:44 AM by willsteele, version 1