Existem convenções de codificação conhecidas do PowerShell?

Existem convenções bem definidas ao programar no PowerShell?

Por exemplo, em scripts que devem ser mantidos a longo prazo, precisamos:

• Use o nome ou o alias real do cmdlet?
• Especifique o nome do parâmetro do cmdlet na íntegra ou apenas parcialmente ( dir -Recurseversus dir -r)
• Ao especificar argumentos de string para cmdlets, você os coloca entre aspas ( New-Object 'System.Int32'versusNew-Object System.Int32
• Ao escrever funções e filtros, você especifica os tipos de parâmetros?
• Você escreve cmdlets no caso correto (oficial)?
• Para palavras-chave como BEGIN...PROCESS...ENDvocê as escreve apenas em maiúsculas?

Parece que o MSDN não possui um documento de convenções de codificação para o PowerShell, enquanto esse documento existe, por exemplo, para C #.

@ Robert Harvey referenciou alguns bons links formais. Por meio de um documento menos formal, meus pensamentos seriam:

Use o nome ou o alias real do cmdlet?

Use o alias apenas se for mais claro que o nome completo. Por exemplo, acho que a maioria das pessoas acharia dirou lsmais clara em um script do que com Get-ChildItembase na experiência anterior (por exemplo, basicamente qualquer pessoa que escreve um script do PowerShell tem uma dessas duas vezes em scripts em lote do DOS ou em scripts do Unix).

Especifique o nome do parâmetro do cmdlet na íntegra ou apenas parcialmente (dir -Recurse versus dir -r)

Em um script, eu soletraria completamente o nome porque (ao contrário do exemplo acima) não consigo pensar em um momento em que a opção mais curta seria realmente mais clara do que explicitada. Os nomes mais curtos das opções são para salvar a digitação. Em uma linha de comando, isso é imperativo. Em um script, as teclas extras valem a pena pela legibilidade e manutenção.

Ao especificar argumentos de seqüência de caracteres para cmdlets, você os coloca entre aspas (New-Object 'System.Int32' versus New-Object System.Int32

A inclusão de argumentos de string entre aspas parece muito mais clara ao ler o código, então eu os incluiria.

Ao escrever funções e filtros, você especifica os tipos de parâmetros?

Somente quando for necessário fazê-lo para resolver a ambiguidade do intérprete (o que acontece). Se você tentar colocar tipos em tudo, é melhor escrever aplicativos de linha de comando C # (o que nem sempre é uma coisa ruim, mas anula a economia de tempo que você obtém com scripts).

Você escreve cmdlets no caso correto (oficial)?

Você deveria . Eu costumo fazer. Quando apressado, sou conhecido por ser um pouco relaxado, pois não importa sintaticamente.

Para palavras-chave como BEGIN ... PROCESS ... END, você as escreve apenas em maiúsculas?

Não. Isso não é FORTRAN. Eu acho que a maioria das pessoas acha beginou Beginmais legível que BEGIN. Há uma razão pela qual associamos todos os limites às gritações on-line e as partes mais mundanas do programa dificultam a legibilidade, chamando a atenção para as partes que menos importam.

O princípio orientador deve ser a legibilidade. Os scripts, por sua natureza de programas rápidos e sujos, se voltam para o código somente para gravação. Todas as suas decisões devem ser tomadas para garantir que você e sua equipe ainda possam entender o script em seis meses. Tente se tirar de si mesmo ao olhar para o seu código e faça a seguinte pergunta: "se eu tivesse iniciado esse trabalho há uma semana (e por isso não estava realmente doutrinado na cultura geral), acharia a maneira como isso está escrito é esclarecedora ou confuso? "

A Microsoft escreveu e publicou um conjunto muito bom de Diretrizes de Desenvolvimento de Cmdlet

Excerto:

Os tópicos nesta seção fornecem diretrizes de desenvolvimento que você pode usar para produzir cmdlets bem formados. Aproveitando a funcionalidade comum fornecida pelo tempo de execução do Windows PowerShell e seguindo estas diretrizes, você pode desenvolver cmdlets robustos com o mínimo de esforço e fornecer ao usuário uma experiência consistente. Além disso, você reduzirá a carga de teste porque a funcionalidade comum não requer novo teste.

Nesta secção

• Diretrizes de desenvolvimento necessárias
• Diretrizes de desenvolvimento fortemente incentivadas
• Diretrizes de desenvolvimento consultivo

Essas diretrizes não se limitam a nenhum idioma (elas não mencionam um idioma) e são perfeitamente aplicáveis ​​ao escrever Cmdlets no PowerShell.

O uso dessas diretrizes ajudará você a escrever Cmdlets claros, detectáveis, utilizáveis ​​e reutilizáveis. Acho que, depois de criar vários módulos do PowerShell, seguir estas diretrizes não é difícil e me ajudou a me tornar um desenvolvedor do PowerShell melhor. Essa habilidade é diretamente utilizável ao escrever scripts simples também.

Como uma segunda resposta; você pode usar o módulo PSScriptAnalyzer para validar seu código.

Invoke-ScriptAnalyzer -Path .

É baseado na análise de código, usando um conjunto de regras. Ele validará o design do código e ajudará a detectar muitos pequenos problemas no seu código.

Nós o incorporamos em nossas construções (usamos construções e um repositório privado para módulos), para detectar problemas de design e qualidade.

Se você estiver interessado, este módulo também contém um formatador de código do PowerShell (que pode usar vários estilos), para que você também possa padronizar o layout do código.

Os documentos na resposta de @ oɔɯǝɹ são uma fonte boa, ainda que um pouco tangencial.

Se você usa o Visual Studio Code, que está planejado para substituir o PowerShell ISE antigo, e instala a extensão VS Code PowerShell , que inclui várias opções de formatação, que foram pelo menos parcialmente baseadas no Guia não oficial de práticas recomendadas e estilo do PowerShell . O VS Code e a extensão do PowerShell são gerenciados pela Microsoft, por isso é tão oficial quanto um guia não oficial.

Eu não concordo com tudo o que eles afirmam. Por exemplo, eu venho de PHP, Java, C # e SQL, onde ponto e vírgula é esperado, se não for necessário. O código parece errado para mim sem eles, então eu os incluo. Se houvesse um, #requires SemicolonTerminatoreu o habilitaria na maioria dos meus scripts, para que eu não precisasse me preocupar com o espaço em branco quebrando uma linha. Eu odeio escapar de retornos de carro e outros VB-ismos.

O restante é a minha opinião:

Use o nome ou o alias real do cmdlet?

Seja inequívoco. Nunca use um alias em um script salvo; até um alias padrão. Não há nada que impeça um usuário de alterar aliases padrão. É mais seguro supor que eles não sejam imutáveis.

Especifique o nome do parâmetro do cmdlet na íntegra ou apenas parcialmente (dir -Recurse versus dir -r)

Mais uma vez, seja inequívoco. Os nomes completos dos parâmetros têm a melhor compatibilidade direta. -rhoje pode ser inequívoco, mas não há nada que impeça que versões futuras de um comando introduzam novos parâmetros. Você usará um IDE (código ISE ou VS). Pressione Ctrl+ Spacee preencha automaticamente esse parâmetro.

Note que ls -r é ambíguo. -ReadOnlyé outro parâmetro deGet-ChildItem .

Ao especificar argumentos de seqüência de caracteres para cmdlets, você os coloca entre aspas (New-Object 'System.Int32' versus New-Object System.Int32

Em geral, as cotações devem ser usadas apenas quando necessário (por exemplo, New-Object -TypeName 'System.Collections.Generic.HashSet[System.Int32]' use aspas simples quando você puder e apenas aspas duplas quando precisar encapsular aspas simples ou incorporar variáveis.

Ao escrever funções e filtros, você especifica os tipos de parâmetros?

Normalmente, a menos que precise especificamente aceitar uma grande variedade de tipos com o mesmo parâmetro e não queira escrever conjuntos de parâmetros individuais.

Você escreve cmdlets no caso correto (oficial)?

Caso Pascal. Sim.

Para palavras-chave como BEGIN ... PROCESS ... END, você as escreve apenas em maiúsculas?

Eu vi declarações, operadores e construções de linguagem como Begin, If, ForEach, -NotIn, bem como begin, if, foreach,-notin . Pessoalmente, prefiro letras minúsculas e deixo comandos como Pascal, mas ambos são igualmente comuns.

Outras:

• Sempre especifique parâmetros. Não confie na ordem posicional. New-Object -TypeName System.Int32acabou New-Object System.Int32. Não sei se isso está de acordo, mas, novamente, parece apoiar a ideia geral de "ser inequívoco".

• Se estou escrevendo um módulo, uso verbos padrão indicados por Get-Verb. Essa lista é extremamente estreita, no entanto, nomes de script autônomos para scripts que somente eu mesmo executamos com freqüência não. O problema com a lista de verbos genéricos é que ela tende para dentro Get-ScriptForSpecificPurposeNoNotThatOneTheOtherOne.ps1. Se estou escrevendo um script que extrai determinadas páginas de um arquivo PDF, não o estou chamando Get-ExtractedAccountPDFPages.ps1. Estou chamandoExtract-AccountPDFPages.ps1 . Não estou preocupado com a descoberta de um script que é executado como um programa em si e não se destina a ser modular por sua própria natureza.

• Quebre as regras quando for mais legível, mais concreto ou mais sustentável.

Ao longo dos anos, houve várias maneiras de escrever nomes com várias palavras para variáveis, funções etc.

É difícil ler PROGRAMAS PARA CLASSIFICAÇÃO DE LOTES.

PROGRAM_FOR_SORTING_LOTS_OF_THINGS é um pouco mais fácil.

program_for_sorting_lots_of_things ainda é mais fácil.

ProgramForSortingLotsOfThings elimina o sublinhado e mantém a legibilidade. O Powershell faz isso pela maior parte.