¿Existen convenciones de codificación de PowerShell bien conocidas?

18

¿Existen convenciones bien definidas al programar en PowerShell?

Por ejemplo, en los scripts que se deben mantener a largo plazo, ¿necesitamos:

  • ¿Usar el nombre o alias del cmdlet real?
  • Especifique el nombre del parámetro de cmdlet completo o solo parcialmente ( dir -Recurseversus dir -r)
  • Al especificar argumentos de cadena para cmdlets, los encierra entre comillas ( New-Object 'System.Int32'versusNew-Object System.Int32
  • Al escribir funciones y filtros, ¿especifica los tipos de parámetros?
  • ¿Escribes cmdlets en el caso correcto (oficial)?
  • Para palabras clave como BEGIN...PROCESS...END¿las escribe solo en mayúsculas?

Parece que MSDN carece de documento de convenciones de codificación para PowerShell, mientras que dicho documento existe, por ejemplo, para C #.

Tahir Hassan
fuente
2
Hay un proyecto comunitario que intenta documentar tales convenciones. github.com/PoshCode/PowerShellPracticeAndStyle . Hay variación, por supuesto, el estilo es algo muy personal.
Chris Dent

Respuestas:

8

@Robert Harvey hizo referencia a algunos buenos enlaces formales. A modo de documento menos formal, mis pensamientos serían:

¿Usar el nombre o alias del cmdlet real?

Solo use el alias si es más claro que el nombre completo. Por ejemplo, creo que la mayoría de la gente lo encontraría diro sería lsmás claro en un script que en Get-ChildItembase a la experiencia previa (por ejemplo, básicamente cualquiera que escriba un script de PowerShell tiene uno de esos dos muchas veces en scripts por lotes de DOS o scripts Unix).

Especifique el nombre del parámetro del cmdlet completo o solo parcialmente (dir -Recurse versus dir -r)

En un guión, deletrearía completamente el nombre porque (a diferencia del ejemplo anterior) no puedo pensar en un momento en que el cambio más corto en realidad sería más claro que deletrearlo. Los nombres de interruptor más cortos son para guardar la escritura. En una línea de comando, esto es imprescindible. En un script, las pulsaciones de teclas adicionales valen la pena por su legibilidad y facilidad de mantenimiento.

Al especificar argumentos de cadena para cmdlets, los encierra entre comillas (New-Object 'System.Int32' versus New-Object System.Int32

El encerrar los argumentos de cadena entre comillas parece mucho más claro al leer el código, por lo que los incluiría.

Al escribir funciones y filtros, ¿especifica los tipos de parámetros?

Solo cuando sea necesario hacerlo para resolver la ambigüedad para el intérprete (lo que sucede). Si va a tratar de poner tipos en todo, también podría ir y escribir aplicaciones de línea de comandos de C # (que no siempre es algo malo, pero niega el ahorro de tiempo que obtiene al hacer scripts).

¿Escribes cmdlets en el caso correcto (oficial)?

Usted debe . Yo suelo hacerlo Cuando tengo prisa, se sabe que soy un poco flojo en el caso, ya que no importa sintácticamente.

Para palabras clave como BEGIN ... PROCESS ... END, ¿las escribe solo en mayúsculas?

No. Esto no es FORTRAN. Creo que la mayoría de la gente encuentra begino Beginmás legible que BEGIN. Hay una razón por la que asociamos todas las mayúsculas con gritos en línea y gritar las partes más mundanas del programa dificulta la legibilidad al llamar la atención sobre las partes que menos importan.

El director rector debe ser legible. Las secuencias de comandos, por su propia naturaleza como programas rápidos y sucios, se desvían hacia el código de solo escritura. Debes tomar todas tus decisiones para asegurarte de que tú y tu equipo puedan entender el guión en seis meses. Trate de quitarse los zapatos cuando mire su código y haga esta pregunta: "si hubiera comenzado este trabajo hace una semana (y no estuviera realmente adoctrinado en la cultura general), la forma en que esto está escrito es esclarecedora o confuso?

Miguel
fuente
2

Microsoft ha escrito y publicado un muy buen conjunto de Directrices de desarrollo de Cmdlet

Extracto:

Los temas de esta sección proporcionan pautas de desarrollo que puede usar para producir cmdlets bien formados. Al aprovechar la funcionalidad común proporcionada por el tiempo de ejecución de Windows PowerShell y al seguir estas pautas, puede desarrollar cmdlets robustos con un mínimo esfuerzo y proporcionar al usuario una experiencia consistente. Además, reducirá la carga de la prueba porque la funcionalidad común no requiere una nueva prueba.

En esta sección

Estas pautas no se limitan a ningún idioma (no mencionan un idioma), y son perfectamente aplicables al escribir Cmdlets en PowerShell.

El uso de estas pautas lo ayudará a escribir Cmdlets claros, reconocibles, utilizables y reutilizables. Después de crear varios módulos de PowerShell, no es difícil y me ayudó a convertirme en un mejor desarrollador de PowerShell. Esa habilidad también se puede usar directamente al escribir guiones simples.

oɔɯǝɹ
fuente
1
Parecen más sobre cómo escribir cmdlets, en lugar de cómo escribir PowerShell.
Philip Kendall el
@PhilipKendall lo hacen de hecho. Puede que esto no responda a la pregunta completa, pero creo que esto agrega valor a la pregunta. Tenga en cuenta que puede escribir sus Cmdlets perfectamente en PowerShell puro, y que estas pautas realmente ayudan con eso también. Si puede escribir un buen Cmdlet en PowerShell, también puede escribir buenos scripts de PowerShell.
2015
1

Como segunda respuesta; puede usar el módulo PSScriptAnalyzer para validar su código.

Invoke-ScriptAnalyzer -Path .

Se basa en el análisis de código, utilizando un conjunto de reglas. Validará el diseño del código y lo ayudará a detectar muchos pequeños problemas en su código.

Lo incorporamos en nuestras compilaciones (utilizamos compilaciones y un repositorio privado para módulos), para detectar problemas de diseño y calidad.

Si está interesado, este módulo también contiene un formateador de código de PowerShell (que puede usar varios estilos), por lo que también puede usarlo para estandarizar el diseño del código.

oɔɯǝɹ
fuente
0

Los documentos en la respuesta de @ oɔɯǝɹ son una buena fuente, aunque algo tangencial.

Si usa Visual Studio Code, que está planeado para reemplazar el antiguo ISE de PowerShell, y luego instala la extensión VS Code PowerShell , que incluye varias opciones de formato que se basaron al menos parcialmente en la Guía de mejores prácticas y estilo no oficiales de PowerShell . Microsoft administra tanto el código VS como la extensión PowerShell, por lo que es tan oficial como una guía no oficial.

No estoy de acuerdo con todo lo que dicen. Por ejemplo, vengo de PHP, Java, C # y SQL, donde se esperan puntos y comas si no se requieren. El código me parece mal sin ellos, así que los incluyo. Si hubiera un #requires SemicolonTerminator, lo habilitaría en la mayoría de mis scripts para no tener que preocuparme de que el espacio en blanco rompa una línea. Odio escapar de los retornos de carro y otros VB-ismos.

El resto de estos son mi opinión:

¿Usar el nombre o alias del cmdlet real?

Sé inequívoco. Nunca use un alias en un guión guardado; incluso un alias predeterminado. No hay nada que impida a un usuario cambiar los alias predeterminados. Es más seguro asumir que no son inmutables.

Especifique el nombre del parámetro del cmdlet completo o solo parcialmente (dir -Recurse versus dir -r)

Nuevamente, sea inequívoco. Los nombres completos de los parámetros tienen la mejor compatibilidad hacia adelante. -rpuede ser inequívoco hoy, pero no hay nada que impida que las futuras versiones de un comando introduzcan nuevos parámetros. Vas a usar un IDE (ya sea ISE o VS Code). Presiona Ctrl+ Spacey completa automáticamente ese parámetro.

Tenga en cuenta que ls -r es ambiguo. -ReadOnlyEs otro parámetro de Get-ChildItem.

Al especificar argumentos de cadena para cmdlets, los encierra entre comillas (New-Object 'System.Int32' versus New-Object System.Int32

En general, las comillas solo deben usarse cuando sea necesario (p New-Object -TypeName 'System.Collections.Generic.HashSet[System.Int32]'. Ej . , Use comillas simples cuando pueda, y solo comillas dobles cuando necesite encapsular comillas simples o incrustar variables.

Al escribir funciones y filtros, ¿especifica los tipos de parámetros?

Normalmente lo hago, a menos que necesite aceptar específicamente una amplia variedad de tipos con el mismo parámetro y no quiera escribir conjuntos de parámetros individuales.

¿Escribes cmdlets en el caso correcto (oficial)?

Estuche Pascal. Si.

Para palabras clave como BEGIN ... PROCESS ... END, ¿las escribe solo en mayúsculas?

He visto declaraciones, operadores y construcciones del lenguaje como Begin, If, ForEach, -NotIn, así como begin, if, foreach, -notin. Personalmente, prefiero las minúsculas y dejo los comandos como Pascal, pero ambos son igualmente comunes.

Otros:

  • Siempre especifique los parámetros. No confíe en el orden posicional. New-Object -TypeName System.Int32terminado New-Object System.Int32. No sé si eso se acordó, pero, una vez más, parece apoyar la idea general de "no ser ambiguo".

  • Si estoy escribiendo un módulo, uso verbos estándar indicados por Get-Verb. Sin embargo, esta lista es extremadamente estrecha, por lo que los nombres de script independientes para scripts que solo yo mismo ejecutaré a menudo no lo hacen. El problema con la lista de verbos genéricos es que tiende hacia dentro Get-ScriptForSpecificPurposeNoNotThatOneTheOtherOne.ps1. Si estoy escribiendo un script que extrae ciertas páginas de un archivo PDF, no lo estoy llamando Get-ExtractedAccountPDFPages.ps1. Lo estoy llamando Extract-AccountPDFPages.ps1. No me preocupa la capacidad de detección de un script que se ejecuta como un programa en sí mismo y no pretende ser modular por su propia naturaleza.

  • Rompe las reglas cuando sea más legible, más concreto o más fácil de mantener.

Pedacitos de tocino
fuente
-3

A lo largo de los años ha habido una variedad de formas de escribir nombres de varias palabras para variables, funciones, etc.

PROGRAMA PARA FORTALECER MUCHAS COSAS es difícil de leer.

PROGRAM_FOR_SORTING_LOTS_OF_THINGS es un poco más fácil.

program_for_sorting_lots_of_things es aún más fácil.

ProgramForSortingLotsOfThings elimina el guión bajo y mantiene la legibilidad. Powershell hace esto en su mayor parte.

MarkH
fuente
Powershell generalmente hace una mezcla de tripa de camello (que sintácticamente no significa nada) y guiones. Por ejemplo, Get-ChildItemcon un guión entre el verbo y el sustantivo.
Andrew dice Reinstate Monica