On this page

    Our Guidelines

    Overview

    This page describes:

    Code Formatting and Conventions

    Formatting

    All code must be properly formatted for a Pull Request (PR) to be merged. For examples of formatting, take a look around the public functions of the projects.

    If you are using VS Code, the project is already configured to help you with that.

    Templates

    No templates yet. Fill in when available.

    Variable Naming

    The naming convention asks for Pascal Case for all parameters, function nouns, method names, property names, field names, etc.
    Local variables created within a function should be in Camel Case.

    Example:

    $GlobalVariable = "this is global"
function Get-GlobalVariable {
    param(
        $InputObject,
        $Filter
    )
    $localVariable = "this is local"
    $global:GlobalVariable
}

    Additional Information:

    Function Naming

    Functions should use proper Verb-Noun names even for private functions and only use Approved Verbs.

    Splatting

    Use splatting whenever a command has 3 or more parameters. Use the $params variable for splatting. If you need to splat more than one command in a pipeline use $Params<command name> (e.g. $ParamsGetContent ) for each command in the pipeline.

    # Single command
$Params = @{
    Name = 'Widget1'
    Id   = '5ABCD98727658'
    Type = 'Custom'
}
Get-Widget @Params

# Multi-command pipeline
$ParamsAddWidget = @{
    Name = 'Widget1'
    Id   = '5ABCD98727658'
    Type = 'Custom'
}
$ParamsSetWidget = @{
    Height = 10
    Width  = 20
    Depth  = 3
}
Add-Widget @ParamsAddWidget | Set-Widget @ParamsSetWidget

    Aliases

    Expand all aliases prior to a PR. No aliases are permitted, including Sort. The PSAnalyzer tests should detect this and issue a failure.

    In-code Documentation

    Limit in-code comments and documentation. If you are using full, command names and PowerShell “best practices”, the code should be fairly self-documenting. Only use comments when doing something that is out of the norm or obscure. If you feel you need to comment the code, you likely need to refactor it.

    Code Separation and File Naming

    • all functions (public and private), classes, and enums should be defined in separate files and organized according to their category.
    • do not define more than one function, class, or enum per file.
    • do not create nested functions (use separate private functions instead).
    • the filename should match the function or enum name.

    Strive for 100% Code Coverage by Tests

    This project strives to be as close to 100% code coverage as possible. If you are submitting a new function (public or private), the PR will not be merged until a unit test has been added that tests all available code paths for the function. The same goes for classes. If you extend the functionality of an existing feature, please add the tests that describe the changes.

    Document as You Go

    The documentation of a project is located in the /docs/ folder and is the source of truth for all documentation.

    We realize documentation is a boring part of coding, but it is a necessary evil. This is not something that can be thrown over the wall unless we gain some dedicated documentation contributors. The only way to keep this project properly documented is to do it as we go and not after the fact.

    Any code submission will be checked for documentation according to its changes.

    Changes To the Build System

    This chapter must describe how to make changes and test them against AppVeyor/Travis.

    Maybe a page dedicated to this topic might be in order.