Esistono convenzioni di codifica di PowerShell ben note?

18

Esistono convenzioni ben definite durante la programmazione in PowerShell?

Ad esempio, negli script che devono essere mantenuti a lungo termine, è necessario:

  • Utilizzare il nome reale del cmdlet o l'alias?
  • Specifica il nome del parametro del cmdlet per intero o solo parzialmente ( dir -Recurse contro dir -r )
  • Quando si specificano gli argomenti di stringa per i cmdlet, li si racchiude tra virgolette ( New-Object 'System.Int32' contro New-Object System.Int32
  • Durante la scrittura di funzioni e filtri si specificano i tipi di parametri?
  • Scrivi i cmdlet nel caso corretto (ufficiale)?
  • Per parole chiave come BEGIN...PROCESS...END le scrivi solo in maiuscolo?

Sembra che MSDN non abbia documenti di convenzione sulla codifica per PowerShell, mentre tale documento esiste ad esempio per C #.

    
posta Tahir Hassan 31.10.2012 - 15:23
fonte

5 risposte

7

@Robert Harvey ha fatto riferimento ad alcuni buoni link formali. Per mezzo di un documento meno formale, i miei pensieri sarebbero:

Use the real cmdlet name or alias?

Usa l'alias solo se è più chiaro del nome completo. Ad esempio, penso che la maggior parte delle persone troverebbe dir o ls più chiaro in uno script rispetto a Get-ChildItem in base all'esperienza precedente (ad esempio, chiunque scriva uno script PowerShell ne ha una di queste due volte in uno script batch DOS o Scripting Unix).

Specify the cmdlet parameter name in full or only partially (dir -Recurse versus dir -r)

In una sceneggiatura, spiegherei completamente il nome perché (a differenza dell'esempio precedente) non riesco a pensare a un momento in cui l'interruttore più corto sarebbe in realtà più chiaro di come lo si scrive. I nomi degli interruttori più brevi servono per salvare la digitazione. A una riga di comando, questo è un imperativo. In uno script, le sequenze di tasti in più valgono la pena di leggibilità e manutenibilità.

When specifying string arguments for cmdlets do you enclose them in quotes (New-Object 'System.Int32' versus New-Object System.Int32

Racchiudere gli argomenti delle stringhe tra virgolette sembra molto più chiaro durante la lettura del codice, quindi includerli.

When writing functions and filters do you specify the types of parameters?

Solo quando c'è bisogno di farlo per risolvere l'ambiguità per l'interprete (che succede). Se hai intenzione di provare a mettere i tipi su tutto, potresti anche scrivere e scrivere le applicazioni della riga di comando C # (che non è sempre una cosa negativa, ma nega il risparmio di tempo che puoi ottenere con lo scripting).

Do you write cmdlets in the (official) correct case?

Tu dovresti . Io di solito faccio. Quando mi sono affrettato, sono stato conosciuto per essere un po 'trascurato sul caso dal momento che non è sintatticamente rilevante.

For keywords like BEGIN...PROCESS...END do you write them in uppercase only?

No. Questo non è FORTRAN. Penso che la maggior parte delle persone trovi begin o Begin più leggibile di BEGIN . C'è una ragione per cui associamo tutte le maiuscole alle urla online e urlare le parti più banali del programma ostacola la leggibilità attirando l'attenzione sulle parti che contano di meno.

Il principio guida dovrebbe essere la leggibilità. Gli script, per la loro stessa natura di programmi veloci e sporchi, virano verso il codice di sola scrittura. Ogni tua decisione dovrebbe essere presa per garantire che tu e il tuo team possiate ancora capire la sceneggiatura in sei mesi. Cerca di toglierti le scarpe quando guardi il tuo codice e fai questa domanda: "se avessi iniziato questo lavoro una settimana fa (e quindi non ero davvero indottrinato nella cultura generale) troverei il modo in cui questo è scritto illuminante o confondendo? "

    
risposta data 01.11.2012 - 19:57
fonte
2

Microsoft ha scritto e pubblicato un ottimo set di Linee guida per lo sviluppo di cmdlet

Estratto:

The topics in this section provide development guidelines that you can use to produce well-formed cmdlets. By leveraging the common functionality provided by the Windows PowerShell runtime and by following these guidelines, you can develop robust cmdlets with minimal effort and provide the user with a consistent experience. Additionally, you will reduce the test burden because common functionality does not require retesting.

In This Section

Queste linee guida non sono limitate a nessuna lingua (non menzionano una lingua) e sono perfettamente applicabili quando si scrivono i cmdlet in PowerShell.

L'utilizzo di queste linee guida ti aiuterà a scrivere cmdlet chiari, rilevabili, utilizzabili e riutilizzabili. Trovo che dopo aver creato diversi moduli PowerShell seguendo queste linee guida non è difficile, e mi ha aiutato a diventare uno sviluppatore PowerShell migliore. Quella abilità è direttamente utilizzabile anche quando si scrivono script semplici.

    
risposta data 25.01.2015 - 16:53
fonte
1

Come seconda risposta; puoi utilizzare il modulo PsScriptAnalyzer per convalidare il tuo codice.

Invoke-ScriptAnalyzer -Path .

Si basa sull'analisi del codice, utilizzando un set di regole. Convaliderà la progettazione del codice e ti aiuterà a rilevare molti piccoli problemi nel tuo codice.

L'abbiamo incorporato nelle nostre build (usiamo build e un repository privato per i moduli), per cogliere problemi di design e di qualità.

Se sei interessato, questo modulo contiene anche un formattatore di codice PowerShell (che può usare più stili), quindi puoi usarlo anche per standardizzare il layout del codice.

    
risposta data 02.05.2018 - 09:10
fonte
0

I documenti nella risposta di @ oɔɯǝɹ sono una buona fonte, anche se in qualche modo tangenziale.

Se utilizzi Visual Studio Code, che è pianificato per sostituire l'obsoleto PowerShell ISE, quindi installa l'estensione PowerShell VS Code , che include diverse opzioni di formattazione che era almeno parzialmente basato sul Migliori pratiche e guida di stile di PowerShell non ufficiale . Sia VS Code che l'estensione PowerShell sono gestiti da Microsoft, quindi è quasi ufficiale come può essere una guida non ufficiale.

Non sono d'accordo con tutto ciò che affermano. Ad esempio, io vengo da PHP, Java, C # e SQL dove sono previsti punti e virgola se non richiesti. Il codice sembra sbagliato per me senza di loro, quindi li includo. Se ci fosse un #requires SemicolonTerminator , lo abiliterei nella maggior parte dei miei script, quindi non devo preoccuparmi di rompere una riga in spazi vuoti. Odio sfuggire a ritorni a capo e altri VB-ismo.

Il resto di questi sono la mia opinione:

Use the real cmdlet name or alias?

Sii inequivocabile. Non usare mai un alias in uno script salvato; anche un alias predefinito. Non c'è nulla che impedisca a un utente di cambiare gli alias predefiniti. È più sicuro supporre che non siano immutabili.

Specify the cmdlet parameter name in full or only partially (dir -Recurse versus dir -r)

Ancora una volta, sii inequivocabile. I nomi dei parametri completi hanno la migliore compatibilità diretta. -r potrebbe essere inequivocabile oggi, ma non c'è nulla che impedisca alle future versioni di un comando di introdurre nuovi parametri. Stai per utilizzare un IDE (codice ISE o VS). Premi Ctrl + Spazio e completa automaticamente tale parametro.

Tieni presente che ls -r è ambiguo. -ReadOnly è un altro parametro di Get-ChildItem .

When specifying string arguments for cmdlets do you enclose them in quotes (New-Object 'System.Int32' versus New-Object System.Int32

In generale, le virgolette dovrebbero essere utilizzate solo quando necessario (ad es., New-Object -TypeName 'System.Collections.Generic.HashSet[System.Int32]' . Utilizza virgolette singole quando puoi, e solo virgolette doppie quando hai bisogno di incapsulare virgolette singole o di inserire variabili.

When writing functions and filters do you specify the types of parameters?

Di solito lo faccio, a meno che non abbia specificamente bisogno di accettare un'ampia varietà di tipi con lo stesso parametro e non voglio scrivere singoli set di parametri.

Do you write cmdlets in the (official) correct case?

Caso Pascal. Sì.

For keywords like BEGIN...PROCESS...END do you write them in uppercase only?

Ho visto istruzioni, operatori e costrutti di linguaggio come Begin , If , ForEach , -NotIn e begin , if , foreach , -notin . Personalmente, preferisco la minuscola e lasciare i comandi come caso Pascal, ma sono entrambi ugualmente comuni.

Altro:

  • Specifica sempre i parametri. Non fare affidamento sull'ordine posizionale. New-Object -TypeName System.Int32 su New-Object System.Int32 . Non so se sia stato concordato, ma, ancora, sembra sostenere l'idea generale di "essere non ambigui".

  • Se sto scrivendo un modulo, uso i verbi standard indicati da Get-Verb . Questo elenco è estremamente limitato, tuttavia, i nomi di script autonomi per script che solo io stesso eseguirò spesso non lo fanno. Il problema con la lista di verbi generici è che tende verso Get-ScriptForSpecificPurposeNoNotThatOneTheOtherOne.ps1 . Se sto scrivendo uno script che estrae determinate pagine da un file PDF, non lo chiamo Get-ExtractedAccountPDFPages.ps1 . Lo chiamo Extract-AccountPDFPages.ps1 . Non sono preoccupato della rilevabilità di uno script che viene eseguito come un programma stesso e non è concepito per essere modulare in base alla sua natura.

  • Rompi le regole quando è più leggibile, più concreto o più gestibile.

risposta data 30.01.2018 - 17:19
fonte
-3

Nel corso degli anni ci sono stati diversi modi per scrivere nomi multi-word per variabili, funzioni, ecc.

PROGRAMFORSORTINGLOTSOFTHINGS è difficile da leggere.

PROGRAM_FOR_SORTING_LOTS_OF_THINGS è un po 'più semplice.

program_for_sorting_lots_of_things è ancora più semplice.

ProgramForSortingLotsOfThings elimina il carattere di sottolineatura e mantiene la leggibilità. Powershell lo fa per la maggior parte.

    
risposta data 28.07.2016 - 16:53
fonte

Leggi altre domande sui tag