Gibt es bekannte PowerShell-Kodierungskonventionen?

Gibt es beim Programmieren in PowerShell klar definierte Konventionen?

In Skripten, die langfristig gepflegt werden sollen, müssen wir zum Beispiel:

• Verwenden Sie den richtigen Cmdlet-Namen oder Alias?
• Geben Sie den Cmdlet-Parameternamen vollständig oder nur teilweise an ( dir -Recurseversus dir -r).
• Wenn Sie Zeichenfolgenargumente für Cmdlets angeben, schließen Sie diese in Anführungszeichen ein ( New-Object 'System.Int32'versusNew-Object System.Int32
• Geben Sie beim Schreiben von Funktionen und Filtern die Arten von Parametern an?
• Schreiben Sie Cmdlets in der richtigen (offiziellen) Schreibweise?
• Bei Stichwörtern wie BEGIN...PROCESS...ENDschreiben Sie sie nur in Großbuchstaben?

Es scheint, dass MSDN keine Kodierungskonventionen für PowerShell enthält, während solche Dokumente beispielsweise für C # existieren.

@ Robert Harvey verwies auf einige gute formale Links. In einem weniger formellen Dokument wären meine Gedanken:

Verwenden Sie den richtigen Cmdlet-Namen oder Alias?

Verwenden Sie den Alias ​​nur, wenn er eindeutiger ist als der vollständige Name. Ich denke zum Beispiel, dass die meisten Leute in einem Skript mehr Klarheit diroder lsKlarheit finden würden als Get-ChildItemaufgrund früherer Erfahrungen.

Geben Sie den Cmdlet-Parameternamen vollständig oder nur teilweise an (dir -Recurse versus dir -r).

In einem Skript würde ich buchstabieren vollständig den Namen , weil ( im Gegensatz zu dem obigen Beispiel) ich nicht an eine Zeit denken kann , wo die kürzeren Einschaltzeiten tatsächlich wären mehr klar , als es formulierend. Kürzere Schalternamen dienen der Ersparnis der Eingabe. In einer Befehlszeile ist dies zwingend erforderlich. In einem Skript lohnen sich die zusätzlichen Tastenanschläge aus Gründen der Lesbarkeit und Wartbarkeit.

Wenn Sie Zeichenfolgenargumente für Cmdlets angeben, setzen Sie diese in Anführungszeichen (New-Object 'System.Int32' im Vergleich zu New-Object System.Int32)

Das Einschließen von Zeichenfolgenargumenten in Anführungszeichen erscheint beim Durchlesen des Codes viel klarer, daher würde ich sie einschließen.

Geben Sie beim Schreiben von Funktionen und Filtern die Arten von Parametern an?

Nur wenn dies erforderlich ist, um Mehrdeutigkeiten für den Interpreter aufzulösen (was jedoch vorkommt). Wenn Sie versuchen, Typen für alles zu erstellen, können Sie auch C # -Befehlszeilenanwendungen schreiben (was nicht immer schlecht ist, aber die Zeitersparnis durch Skripten zunichte macht).

Schreiben Sie Cmdlets in der richtigen (offiziellen) Schreibweise?

Du solltest . Das mache ich normalerweise . Wenn ich es eilig habe, war ich in der Sache ein wenig nachlässig, da es syntaktisch keine Rolle spielt.

Schreiben Sie Stichwörter wie BEGIN ... PROCESS ... END nur in Großbuchstaben?

Nein, das ist nicht FORTRAN. Ich denke die meisten Leute finden beginoder Beginbesser lesbar als BEGIN. Es gibt einen Grund, warum wir alle Großbuchstaben mit Online-Brüllen und Brüllen der banalsten Teile des Programms in Verbindung bringen, die die Lesbarkeit behindern, indem wir die Aufmerksamkeit auf die Teile lenken, die am wenigsten wichtig sind.

Das Leitmotiv sollte die Lesbarkeit sein. Skripte sind von Natur aus schnelle und unsaubere Programme und tendieren zu schreibgeschütztem Code. Sie sollten jede Entscheidung treffen, um sicherzustellen, dass Sie und Ihr Team das Skript auch in sechs Monaten noch verstehen können. Versuchen Sie, sich aus Ihren eigenen Schuhen zu befreien, wenn Sie sich Ihren Code ansehen, und fragen Sie: "Wenn ich diesen Job vor einer Woche begonnen hätte (und damit nicht wirklich in die allgemeine Kultur eingeweiht wäre), würde ich die Art und Weise, wie dies geschrieben steht, erhellen oder verwirrend? "

Microsoft hat sehr gute Cmdlet-Entwicklungsrichtlinien verfasst und veröffentlicht

Auszug:

Die Themen in diesem Abschnitt enthalten Entwicklungsrichtlinien, anhand derer Sie wohlgeformte Cmdlets erstellen können. Indem Sie die allgemeinen Funktionen der Windows PowerShell-Laufzeitumgebung nutzen und diese Richtlinien befolgen, können Sie mit minimalem Aufwand robuste Cmdlets entwickeln und dem Benutzer eine konsistente Benutzererfahrung bieten. Darüber hinaus reduzieren Sie die Testlast, da für die allgemeine Funktionalität kein erneutes Testen erforderlich ist.

In diesem Abschnitt

• Erforderliche Entwicklungsrichtlinien
• Stark ermutigte Entwicklungsrichtlinien
• Entwicklungsrichtlinien

Diese Richtlinien sind nicht auf eine Sprache beschränkt (sie erwähnen keine Sprache) und sind perfekt anwendbar, wenn Cmdlets in PowerShell geschrieben werden.

Mithilfe dieser Richtlinien können Sie eindeutige, erkennbare, verwendbare und wiederverwendbare Cmdlets erstellen. Nachdem ich mehrere PowerShell-Module gemäß diesen Richtlinien erstellt habe, fällt es mir nicht schwer, mich zu einem besseren PowerShell-Entwickler zu entwickeln. Diese Fähigkeit ist auch beim Schreiben einfacher Skripte direkt anwendbar.

Als zweite Antwort; Sie können das PSScriptAnalyzer- Modul verwenden, um Ihren Code zu validieren.

Invoke-ScriptAnalyzer -Path .

Es basiert auf einer Code-Analyse unter Verwendung eines Regelsatzes. Es validiert das Code-Design und hilft Ihnen dabei, viele kleine Probleme in Ihrem Code zu erkennen.

Wir haben es in unsere Builds integriert (wir verwenden Builds und ein privates Repository für Module), um Design- und Qualitätsprobleme zu erkennen.

Wenn Sie interessiert sind, enthält dieses Modul auch einen PowerShell-Code-Formatierer (der mehrere Stile verwenden kann), sodass Sie damit auch das Code-Layout standardisieren können.

Die Dokumente in @ oɔɯǝɹs Antwort sind eine gute, wenn auch etwas tangentiale Quelle.

Wenn Sie Visual Studio Code verwenden, der die veraltete PowerShell ISE ersetzen soll, installieren Sie die VS Code PowerShell-Erweiterung , enthält dies mehrere Formatierungsoptionen, die zumindest teilweise auf dem inoffiziellen PowerShell Best Practices and Style Guide basieren . Sowohl VS Code als auch die PowerShell-Erweiterung werden von Microsoft verwaltet. Sie ist also so offiziell wie ein inoffizieller Leitfaden.

Ich stimme nicht mit allen Aussagen überein. Zum Beispiel komme ich aus PHP, Java, C # und SQL, wo Semikolons erwartet werden, wenn sie nicht benötigt werden. Code sieht für mich falsch aus , ohne sie, also schließe ich sie ein. Wenn es eine geben #requires SemicolonTerminatorwürde, würde ich sie für die meisten meiner Skripte aktivieren, damit ich mir keine Gedanken über Leerzeichen machen muss, die eine Zeile umbrechen. Ich hasse es, Wagenrückläufen und anderen VB-Ismen zu entkommen.

Der Rest ist meiner Meinung nach:

Verwenden Sie den richtigen Cmdlet-Namen oder Alias?

Seien Sie eindeutig. Verwenden Sie niemals einen Alias ​​in einem gespeicherten Skript. sogar ein Standardalias. Es gibt nichts, was einen Benutzer daran hindert, Standardaliase zu ändern. Es ist sicherer anzunehmen, dass sie nicht unveränderlich sind.

Geben Sie den Cmdlet-Parameternamen vollständig oder nur teilweise an (dir -Recurse versus dir -r).

Seien Sie wieder eindeutig. Vollständige Parameternamen weisen die beste Vorwärtskompatibilität auf. -rmag heute eindeutig sein, aber es gibt nichts, was zukünftige Versionen eines Befehls davon abhält, neue Parameter einzuführen. Sie verwenden eine IDE (entweder ISE oder VS Code). SchlagenCtrl + Spaceund vervollständigen Sie diesen Parameter automatisch.

Beachten Sie, dass ls -r ist nicht eindeutig. -ReadOnlyist ein weiterer Parameter von Get-ChildItem.

Wenn Sie Zeichenfolgenargumente für Cmdlets angeben, setzen Sie diese in Anführungszeichen (New-Object 'System.Int32' im Vergleich zu New-Object System.Int32)

Im Allgemeinen sollten Anführungszeichen nur verwendet werden, wenn dies erforderlich ist (z. B. New-Object -TypeName 'System.Collections.Generic.HashSet[System.Int32]' . Verwenden Sie einfache Anführungszeichen, wenn Sie können, und nur doppelte Anführungszeichen, wenn Sie einfache Anführungszeichen einkapseln oder Variablen einbetten müssen.

Geben Sie beim Schreiben von Funktionen und Filtern die Arten von Parametern an?

Das tue ich normalerweise, es sei denn, ich muss speziell eine Vielzahl von Typen mit demselben Parameter akzeptieren und möchte keine einzelnen Parametersätze schreiben.

Schreiben Sie Cmdlets in der richtigen (offiziellen) Schreibweise?

Pascal Fall. Ja.

Schreiben Sie Stichwörter wie BEGIN ... PROCESS ... END nur in Großbuchstaben?

Ich habe Aussagen gesehen, Operatoren und Sprachkonstrukte wie Begin, If, ForEach, -NotInsowie begin, if, foreach,-notin . Ich persönlich bevorzuge Kleinbuchstaben und lasse Befehle in Pascal-Schreibweise, aber beide sind gleich häufig.

Andere:

• Geben Sie immer Parameter an. Verlassen Sie sich nicht auf die Positionsreihenfolge. New-Object -TypeName System.Int32vorbei New-Object System.Int32. Ich weiß nicht, ob das vereinbart ist, aber es scheint die allgemeine Idee von "eindeutig sein" zu stützen.

• Wenn ich ein Modul schreibe, verwende ich die mit gekennzeichneten Standardverben Get-Verb. Diese Liste ist jedoch extrem eng, sodass eigenständige Skriptnamen für Skripte, die nur ich selbst häufig ausführe, nicht verwendet werden. Das Problem mit der generischen Verbliste ist, dass sie in Richtung hinein tendiert Get-ScriptForSpecificPurposeNoNotThatOneTheOtherOne.ps1. Wenn ich ein Skript schreibe, das bestimmte Seiten aus einer PDF-Datei extrahiert, rufe ich es nicht auf Get-ExtractedAccountPDFPages.ps1. Ich rufe es anExtract-AccountPDFPages.ps1 . Ich bin nicht besorgt über die Auffindbarkeit eines Skripts, das selbst als Programm ausgeführt wird und von Natur aus nicht modular sein soll.

• Brechen Sie die Regeln, wenn sie lesbarer, konkreter oder wartbarer sind.

Im Laufe der Jahre gab es verschiedene Möglichkeiten, Namen mit mehreren Wörtern für Variablen, Funktionen usw. zu schreiben.

PROGRAMM FÜRSORTIEREN VON LOTSOFTHINGS ist schwer zu lesen.

PROGRAM_FOR_SORTING_LOTS_OF_THINGS ist etwas einfacher.

program_for_sorting_lots_of_things ist noch einfacher.

ProgramForSortingLotsOfThings beseitigt den Unterstrich und behält die Lesbarkeit bei. Powershell macht das zum größten Teil.