Standards

Standards

Script files

Script files should

• have the keyword function and the name of the function on the same line
• have help text detailing the function of the code at the top (For functions this must be inside the function)
• have a [CmdletBinding()] property
• have an [OutputType()] property that must contain one or more OutputTypes
• have a param block (under consideration for removal and is currently disabled)
• have any parameters in the param block detailed with a .PARAMETER in the help text
• have variable types for all parameters

Module files

Modules should

• have one or more functions in them
• have a valid accompanying module manifest

Module manifests should

• have all public functions from the module exported
• pass a test-manifest check

When testing a module

• each function is extracted and is then tested as a script file

Projects

Projects should

• adhere to the project structure

    ProjectPath
    |
    -Source
    |     |
    |     -Module
    |     |     |
    |     |     -Public
    |     |     -Private
    |     -Module
    |           |
    |           -Public
    |           -Private
    -Tests
         |
         -Unit
             |
             -Module
             -Module

• have one or more modules in them
  • made up of individual script functions
    • public functons use PowerShell approved verbs and singular nouns. For approved verbs see (for v5.1) or (for v7.1)
    • public functions have a corresponding test file
    • private functions do not follow the verb-noun format
• should not have compiled modules

When testing a project

• each function file is tested as a script file

Help

The HelpRules file is a HashTable of the help properties (elements) that you want to enforce in your help comments

The list of possible elements to choose from are:

• .SYNOPSIS
• .DESCRIPTION
• .PARAMETER
• .EXAMPLE
• .INPUTS
• .OUTPUTS
• .NOTES
• .LINK
• .COMPONENT
• .ROLE
• .FUNCTIONALITY
• .FORWARDHELPTARGETNAME
• .FORWARDHELPCATEGORY
• .REMOTEHELPRUNSPACE
• .EXTERNALHELP

Each element is in a number sequence and they are processed in their numerical order. If a key is required then it must exist, and have between MinOccurrences and MaxOccurrences occurences in the help block under test.

Note: If the test finds an element that does not appear in the help rules file then the test will fail

An example HelpRules file is shown here:

    '1' = @{
        Key = '.SYNOPSIS'
        Required = $true
        MinOccurrences = 1
        MaxOccurrences = 1
    }
    '2' = @{
        Key = '.DESCRIPTION'
        Required = $true
        MinOccurrences = 1
        MaxOccurrences = 1
    }
    '3' = @{
        Key = '.PARAMETER'
        Required = $false
        MinOccurrences = 0
        MaxOccurrences = 0
    }
    '4' = @{
        Key = '.EXAMPLE'
        Required = $true
        MinOccurrences = 1
        MaxOccurrences = 100
        # MaxOccurrences = 1
    }
    '5' = @{
        Key = '.INPUTS'
        Required = $false
        MinOccurrences = 0
        MaxOccurrences = 0
    }
    '6' = @{
        Key = '.OUTPUTS'
        Required = $false
        MinOccurrences = 0
        MaxOccurrences = 0
    }
    '7' = @{
        Key = '.NOTES'
        Required = $false
        MinOccurrences = 0
        MaxOccurrences = 0
    }
    '8' = @{
        Key = '.LINK'
        Required = $false
        MinOccurrences = 0
        MaxOccurrences = 0
    }
}

Examples

An example of a valid public function file:

function Get-File {
    <#
        .SYNOPSIS
        Get the content of the file

        .DESCRIPTION
        Get and return the content of the passed PowerShell file

        .PARAMETER Path
        A string containing PowerShell filename

        .EXAMPLE
        Get-File -Path $File

    #>
    [CmdletBinding()]
    [OutputType([System.String[]])]
    param (
        [parameter(Mandatory = $true)]
        [string]$Path
    )

    $fileContent = Get-Content -Path $Path -Raw

    return $fileContent

}