Guia de Estilo PowerShell

Introdução

Este artigo fornece um guia de estilo abrangente para PowerShell, com foco em legibilidade, consistência e boas práticas para escrever scripts limpos e fáceis de manter. Este guia é baseado no PowerShell Practice and Style Guide.

Layout e Formatação do Código

Mantenha a Consistência no Layout

Use indentação, comprimento de linha e capitalização consistentes para melhorar a legibilidade.

Convenções de Capitalização

• Use PascalCase para todos os identificadores públicos.
• Use lowercase para palavras-chave da linguagem.
• Use UPPERCASE para palavras-chave em ajuda baseada em comentários.

function Write-Host {
    [CmdletBinding()]
    param(
        [psobject]$Object,
        [switch]$NoNewline
    )
}

One True Brace Style (OTBS)

Coloque chaves de abertura no final da linha e chaves de fechamento em uma nova linha.

if ($value -gt 0) {
    "Positive"
} else {
    "Non-Positive"
}

CmdletBinding e Ordem dos Blocos

Inicie funções com [CmdletBinding()] e siga a ordem param(), begin, process, end.

[CmdletBinding()]
param ()
process { }
end { }

Indentação

Utilize quatro espaços por nível de indentação.

foreach ($item in $list) {
    Do-Something -Param $item
}

Comprimento Máximo da Linha

Limite as linhas a 115 caracteres. Use splatting ou parênteses para quebras de linha limpas.

$Params = @{
    Name = "Explorer"
    Verbose = $true
}
Get-Process @Params

Linhas em Branco e Espaços

• Use duas linhas em branco ao redor de funções.
• Evite espaços no final das linhas.
• Utilize espaços ao redor de operadores e parâmetros.

$Value = 5 + 3

Evite Pontos e Vírgulas

Não utilize ponto e vírgula como terminador de linha.

$Options = @{
    Margin = 2
    Padding = 2
}

Funções

Funções Básicas

• Evite usar return. Saída direta de objetos.
• Deixe um espaço entre o nome da função e os parâmetros.

function MyFunction ($param1, $param2) {
    ...
}

Funções Avançadas

• Use a nomenclatura <Verbo>-<Substantivo>.
• Sempre utilize [CmdletBinding()].
• Retorne objetos no bloco process {}.
• Especifique OutputType.

function Get-Example {
    [CmdletBinding()]
    [OutputType([psobject])]
    param (
        [int]$Id
    )
    process {
        New-Object -TypeName psobject -Property @{ ID = $Id }
    }
}

Documentação e Comentários

Diretrizes Gerais para Comentários

• Mantenha os comentários atualizados.
• Escreva em inglês, utilizando frases completas quando necessário.
• Explique a lógica e decisões, não o óbvio do código.

# Ajustar a margem devido à sobreposição da interface
$Margin = $Margin + 2

Comentários em Bloco

Use # ou <# ... #> para comentários longos.

<#
    .SYNOPSIS
        Exemplo de uso de comentário em bloco.
#>

Comentários Inline

Alinhe comentários inline para melhor clareza.

$Options = @{
    Margin = 2      # Ajuste da interface
    Padding = 2     # Espaço ao redor do texto
}

Ajuda Baseada em Comentários

Inclua sempre ajuda nos seus scripts.

function Get-Example {
    <#
    .SYNOPSIS
        Recupera dados de exemplo.
    .EXAMPLE
        Get-Example
    #>
}

Legibilidade

Indente Seu Código

Indente dentro das estruturas para maior clareza.

foreach ($item in $items) {
    Process-Item $item
}

Evite Crase (“`)

Prefira splatting para quebras de linha ao invés de crase.

$Params = @{
    Class = "Win32_LogicalDisk"
    Filter = "DriveType=3"
}
Get-WmiObject @Params

Convenções de Nomenclatura

Use Nomes Completos de Comandos e Parâmetros

Evite aliases e abreviações.

Get-Process -Name Explorer

Use Caminhos Explícitos

Prefira caminhos completos ou utilize $PSScriptRoot.

Get-Content "$PSScriptRoot\README.md"

Evite o Uso de ~

Utilize ${Env:UserProfile} ao invés de ~.

cd ${Env:UserProfile}

Conclusão

Seguir estas diretrizes garante que seus scripts PowerShell sejam limpos, consistentes e mais fáceis de manter, especialmente em ambientes colaborativos.

Para mais detalhes, consulte o PowerShell Practice and Style Guide.