Czy są znane konwencje kodowania PowerShell?

Czy istnieją jakieś dobrze zdefiniowane konwencje podczas programowania w PowerShell?

Na przykład w skryptach, które mają być utrzymywane długoterminowo, musimy:

• Używać prawdziwej nazwy lub aliasu polecenia cmdlet?
• Podaj nazwę parametru cmdlet w całości lub tylko częściowo (w dir -Recurseporównaniu dir -r)
• Podając argumenty łańcuchowe dla poleceń cmdlet, czy umieszczasz je w cudzysłowach (w New-Object 'System.Int32'porównaniu zNew-Object System.Int32
• Czy pisząc funkcje i filtry określasz typy parametrów?
• Czy piszesz polecenia cmdlet w (oficjalnej) poprawnej sprawie?
• W przypadku słów kluczowych, takich jak BEGIN...PROCESS...ENDczy piszesz je tylko dużymi literami?

Wydaje się, że MSDN nie ma dokumentu konwencji kodowania dla PowerShell, podczas gdy taki dokument istnieje na przykład dla C #.

@Robert Harvey odniósł się do niektórych dobrych linków formalnych. Jako mniej formalny dokument moje myśli będą następujące:

Używać prawdziwej nazwy lub aliasu polecenia cmdlet?

Używaj aliasu tylko wtedy, gdy jest wyraźniejszy niż pełna nazwa. Na przykład, myślę, że większość ludzi uznałaby dirlub lsskreśliła w skrypcie bardziej niż Get-ChildItemna podstawie wcześniejszych doświadczeń (np. W zasadzie każdy, kto pisze skrypt PowerShell, ma jedno z tych dwóch wielokrotnie w skryptach wsadowych DOS lub skryptach uniksowych).

Podaj nazwę parametru cmdlet w całości lub tylko częściowo (dir -Recurse versus dir -r)

W skrypcie w pełni przeliterowałbym nazwę, ponieważ (w przeciwieństwie do powyższego przykładu) nie mogę wymyślić czasu, w którym krótszy przełącznik byłby bardziej wyraźny niż pisownia. Krótsze nazwy przełączników mają zaoszczędzić na pisaniu. W wierszu polecenia jest to konieczne. W skrypcie dodatkowe naciśnięcia klawiszy są tego warte ze względu na czytelność i łatwość konserwacji.

Podając argumenty łańcuchowe dla poleceń cmdlet, czy umieszczasz je w cudzysłowie (New-Object 'System.Int32' vs. New-Object System.Int32

Umieszczanie argumentów ciągów w cudzysłowach wydaje się o wiele bardziej czytelne podczas czytania kodu, więc bym je uwzględnił.

Czy pisząc funkcje i filtry określasz typy parametrów?

Tylko wtedy, gdy zajdzie taka potrzeba, aby rozwiązać niejednoznaczność tłumacza (co się zdarza). Jeśli masz zamiar umieścić typy na wszystkim, równie dobrze możesz napisać aplikacje wiersza polecenia C # (co nie zawsze jest złe, ale neguje to oszczędność czasu, którą zyskujesz dzięki skryptom).

Czy piszesz polecenia cmdlet w (oficjalnej) poprawnej sprawie?

Państwo powinno . I zwykle zrobić. Kiedy się spieszyłem, byłem pewien, że jestem trochę rozluźniony w sprawie, ponieważ nie ma to znaczenia składniowego.

Dla słów kluczowych, takich jak BEGIN ... PROCESS ... END, czy piszesz je tylko dużymi literami?

Nie. To nie jest FORTRAN. Myślę, że większość ludzi uważa beginlub jest Beginbardziej czytelna niż BEGIN. Istnieje powód, dla którego łączymy wszystkie znaki z krzykiem online i wykrzykiwaniem najbardziej przyziemnych części programu utrudnia czytelność, zwracając uwagę na te, które mają najmniejsze znaczenie.

Główną zasadą powinna być czytelność. Skrypty, ze swej natury jako szybkie i brudne programy, skręcają w kierunku kodu tylko do zapisu. Należy podjąć każdą decyzję, aby zapewnić, że Ty i Twój zespół będziecie w stanie zrozumieć scenariusz w ciągu sześciu miesięcy. Spróbuj zerwać się z butów, patrząc na swój kod i zadaj pytanie: „gdybym zaczął tę pracę tydzień temu (a tak naprawdę nie byłam indoktrynowana w ogólnej kulturze), czy znalazłbym sposób, w jaki napisano to w sposób pouczający lub mylące? ”

Microsoft napisał i opublikował bardzo dobry zestaw Wytycznych programistycznych Cmdlet

Fragment:

Tematy w tej sekcji zawierają wytyczne programistyczne, których można używać do tworzenia dobrze sformatowanych poleceń cmdlet. Korzystając ze wspólnej funkcjonalności środowiska uruchomieniowego Windows PowerShell i postępując zgodnie z tymi wytycznymi, możesz opracować solidne polecenia cmdlet przy minimalnym wysiłku i zapewnić użytkownikowi spójne wrażenia. Dodatkowo zmniejszysz obciążenie testowe, ponieważ powszechna funkcjonalność nie wymaga ponownego testowania.

W tej sekcji

• Wymagane wytyczne programistyczne
• Mocno zachęcane wytyczne dotyczące rozwoju
• Doradcze wytyczne dotyczące rozwoju

Te wytyczne nie są ograniczone do żadnego języka (nie wspominają o języku) i mają doskonałe zastosowanie podczas pisania poleceń cmdlet w programie PowerShell.

Korzystanie z tych wskazówek pomoże Ci napisać jasne, dostępne do odkrycia, użyteczne i wielokrotnego użytku polecenia cmdlet. Uważam, że po utworzeniu kilku modułów PowerShell przestrzeganie tych wytycznych nie jest trudne i pomogło mi zostać lepszym programistą PowerShell. Tę umiejętność można bezpośrednio wykorzystać także podczas pisania prostych skryptów.

Jako druga odpowiedź; możesz użyć modułu PSScriptAnalyzer do sprawdzenia poprawności kodu.

Invoke-ScriptAnalyzer -Path .

Opiera się na analizie kodu przy użyciu zestawu reguł. Sprawdza poprawność projektu kodu i pomaga wykryć wiele drobnych problemów w kodzie.

Włączyliśmy go do naszych kompilacji (korzystamy z kompilacji i prywatnego repozytorium modułów), aby wychwycić problemy projektowe i jakościowe.

Jeśli jesteś zainteresowany, ten moduł zawiera również formatyzator kodu PowerShell (który może używać wielu stylów), więc możesz go użyć do standaryzacji układu kodu.

Dokumenty w odpowiedzi @ o @ są dobrym, choć nieco stycznym źródłem.

Jeśli korzystasz z programu Visual Studio Code, który ma zastąpić starzejący się PowerShell ISE, a następnie zainstalujesz rozszerzenie VS Code PowerShell , które zawiera kilka opcji formatowania, które przynajmniej częściowo były oparte na Nieoficjalnych najlepszych praktykach i przewodniku po stylu PowerShell . Zarówno kod VS, jak i rozszerzenie PowerShell są zarządzane przez Microsoft, więc jest to tak oficjalne, jak może być nieoficjalny przewodnik.

Nie zgadzam się ze wszystkim, co twierdzą. Na przykład pochodzę z PHP, Java, C # i SQL, w których można oczekiwać średników, jeśli nie są wymagane. Bez nich kod wygląda na niewłaściwy , więc je uwzględniam. Gdyby istniał #requires SemicolonTerminator, włączałbym go na większości moich skryptów, więc nie muszę się martwić, że białe znaki przerywają linię. Nienawidzę uciekających powrotów karetki i innych VB-ów.

Reszta to moja opinia:

Używać prawdziwej nazwy lub aliasu polecenia cmdlet?

Bądź jednoznaczny. Nigdy nie używaj aliasu w zapisanym skrypcie; nawet domyślny alias. Nic nie powstrzymuje użytkownika od zmiany domyślnych aliasów. Bezpieczniej jest założyć, że nie są niezmienne.

Podaj nazwę parametru cmdlet w całości lub tylko częściowo (dir -Recurse versus dir -r)

Ponownie bądźcie jednoznaczni. Pełne nazwy parametrów mają najlepszą kompatybilność do przodu. -rmogą być dziś jednoznaczne, ale nic nie stoi na przeszkodzie, aby przyszłe wersje polecenia wprowadzały nowe parametry. Będziesz używać IDE (kod ISE lub VS). Naciśnij Ctrl+ Spacei autouzupełniaj ten parametr.

Zauważ, że ls -r jest to niejednoznaczne. -ReadOnlyjest kolejnym parametrem Get-ChildItem.

Podając argumenty łańcuchowe dla poleceń cmdlet, czy umieszczasz je w cudzysłowie (New-Object 'System.Int32' vs. New-Object System.Int32

Zasadniczo cudzysłowy powinny być używane tylko wtedy, gdy jest to konieczne (np New-Object -TypeName 'System.Collections.Generic.HashSet[System.Int32]'. Używaj pojedynczych cudzysłowów, gdy możesz, i tylko podwójne cudzysłowy, gdy potrzebujesz obudować pojedyncze cudzysłowy lub osadzić zmienne.

Czy pisząc funkcje i filtry określasz typy parametrów?

Zwykle tak robię, chyba że muszę konkretnie zaakceptować szeroką gamę typów z tym samym parametrem i nie chcę pisać poszczególnych zestawów parametrów.

Czy piszesz polecenia cmdlet w (oficjalnej) poprawnej sprawie?

Sprawa Pascala. Tak.

Dla słów kluczowych, takich jak BEGIN ... PROCESS ... END, czy piszesz je tylko dużymi literami?

Widziałem oświadczenia, operatorów i konstrukcje języka jak Begin, If, ForEach, -NotInjak również begin, if, foreach, -notin. Osobiście wolę małe litery i zostawiam polecenia jako małe litery Pascala, ale oba są równie popularne.

Inne:

• Zawsze określaj parametry. Nie polegaj na porządku pozycyjnym. New-Object -TypeName System.Int32ponad New-Object System.Int32. Nie wiem, czy zostało to uzgodnione, ale wydaje się, że potwierdza to ogólną ideę „bądź jednoznaczny”.

• Jeśli piszę moduł, używam standardowych czasowników wskazanych przez Get-Verb. Ta lista jest jednak bardzo wąska, więc samodzielne nazwy skryptów dla skryptów, które tylko ja będę uruchamiał, często nie. Problem z ogólną listą czasowników polega na tym, że ma ona tendencję do Get-ScriptForSpecificPurposeNoNotThatOneTheOtherOne.ps1. Jeśli piszę skrypt, który wyodrębnia niektóre strony z pliku PDF, nie nazywam go Get-ExtractedAccountPDFPages.ps1. Nazywam to Extract-AccountPDFPages.ps1. Nie martwię się o możliwość wykrycia skryptu, który działa jako sam program i nie jest z natury modułowy.

• Łam zasady, gdy jest bardziej czytelne, bardziej konkretne lub łatwiejsze w utrzymaniu.

Przez lata istniało wiele sposobów na pisanie nazw wielu słów dla zmiennych, funkcji itp.

PROGRAMFORSORTOWANIE LICZBYSOFTHINGS jest trudny do odczytania.

PROGRAM_FOR_SORTING_LOTS_OF_THINGS jest nieco łatwiejszy.

program_for_sorting_lots_of_things jest jeszcze łatwiejszy.

ProgramForSortingLotsOfThings usuwa znak podkreślenia i zachowuje czytelność. Powershell robi to najczęściej.