Guía de Estilo PowerShell

Introducción

Este artículo ofrece una guía de estilo completa para PowerShell, enfocada en la legibilidad, consistencia y buenas prácticas para escribir scripts limpios y mantenibles. Esta guía se basa en el PowerShell Practice and Style Guide.

Diseño y Formato del Código

Mantener la Consistencia en el Diseño

Asegúrate de utilizar una indentación, longitud de línea y uso de mayúsculas consistente para mejorar la legibilidad.

Convenciones de Capitalización

• Usa PascalCase para todos los identificadores públicos.
• Usa lowercase para palabras clave del lenguaje.
• Usa UPPERCASE para palabras clave en ayudas basadas en comentarios.

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

One True Brace Style (OTBS)

Coloca las llaves de apertura al final de la línea y las de cierre en una nueva línea.

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

CmdletBinding y Orden de Bloques

Inicia las funciones con [CmdletBinding()] y sigue el orden param(), begin, process, end.

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

Indentación

Usa cuatro espacios por nivel de indentación.

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

Longitud Máxima de Línea

Limita las líneas a 115 caracteres. Usa splatting o paréntesis para dividir líneas de manera limpia.

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

Líneas en Blanco y Espacios

• Deja dos líneas en blanco alrededor de las funciones.
• No uses espacios al final de las líneas.
• Usa espacios alrededor de operadores y parámetros.

$Value = 5 + 3

Evitar Punto y Coma

No utilices punto y coma como terminador de línea.

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

Funciones

Funciones Básicas

• Evita usar return. Devuelve objetos directamente.
• Deja un espacio entre el nombre de la función y los parámetros.

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

Funciones Avanzadas

• Usa la convención <Verbo>-<Sustantivo>.
• Siempre usa [CmdletBinding()].
• Devuelve objetos dentro del bloque process {}.
• Especifica el atributo OutputType.

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

Documentación y Comentarios

Guía General de Comentarios

• Mantén los comentarios actualizados.
• Escribe en inglés y usa oraciones completas cuando sea necesario.
• Explica decisiones, no describas lo obvio del código.

# Ajustar el margen por superposición de la interfaz
$Margin = $Margin + 2

Comentarios en Bloque

Utiliza # o <# ... #> para comentarios largos.

<#
    .SYNOPSIS
        Ejemplo de comentario en bloque.
#>

Comentarios Inline

Alinea los comentarios inline para mayor claridad.

$Options = @{
    Margin = 2      # Ajuste de la interfaz
    Padding = 2     # Espacio alrededor del texto
}

Ayuda Basada en Comentarios

Incluye siempre ayuda en tus scripts.

function Get-Example {
    <#
    .SYNOPSIS
        Recupera datos de ejemplo.
    .EXAMPLE
        Get-Example
    #>
}

Legibilidad

Indenta Tu Código

Indenta correctamente dentro de las estructuras.

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

Evita el Uso de Backticks

Utiliza splatting en lugar de backticks para dividir líneas.

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

Convenciones de Nombres

Usa Nombres Completos para Comandos y Parámetros

Evita alias y abreviaciones.

Get-Process -Name Explorer

Usa Rutas Explícitas

Prefiere rutas completas o utiliza $PSScriptRoot.

Get-Content "$PSScriptRoot\README.md"

Evita el Uso de ~

Utiliza ${Env:UserProfile} en lugar de ~.

cd ${Env:UserProfile}

Conclusión

Seguir estas directrices asegura que tus scripts PowerShell sean limpios, consistentes y fáciles de mantener, especialmente en entornos colaborativos.

Para más detalles, consulta la PowerShell Practice and Style Guide.