Существуют ли общепринятые соглашения о кодировании PowerShell?

Существуют ли четко определенные соглашения при программировании в PowerShell?

Например, в сценариях, которые должны поддерживаться в течение длительного времени, нам нужно:

• Использовать настоящее имя или псевдоним командлета?
• Укажите имя параметра командлета полностью или только частично (по dir -Recurseсравнению с dir -r)
• При указании строковых аргументов для командлетов вы заключаете их в кавычки (по New-Object 'System.Int32'сравнению сNew-Object System.Int32
• При написании функций и фильтров вы указываете типы параметров?
• Вы пишете командлеты в (официальном) правильном регистре?
• Для таких слов, как BEGIN...PROCESS...ENDвы пишете их только в верхнем регистре?

Кажется, что в MSDN отсутствует документ по соглашениям о кодировании для PowerShell, хотя такой документ существует, например, для C #.

@ Роберт Харви ссылался на несколько хороших официальных ссылок. В качестве менее формального документа мои мысли были бы:

Использовать настоящее имя или псевдоним командлета?

Используйте псевдоним, только если он более понятен, чем полное имя. Например, я думаю, что большинство людей находят dirили lsболее понятны в сценарии, чем Get-ChildItemна основе предыдущего опыта (например, в основном любой, кто пишет сценарий PowerShell, имеет один из этих двух раз в пакетных сценариях DOS или сценариях Unix).

Укажите имя параметра командлета полностью или только частично (dir -Recurse против dir -r)

В сценарии я бы полностью произнес имя по буквам, потому что (в отличие от приведенного выше примера) я не могу вспомнить время, когда более короткое переключение будет на самом деле более ясным, чем его написание. Более короткие имена переключателей для сохранения ввода. В командной строке это обязательно. В сценарии дополнительные нажатия клавиш того стоят для удобства чтения и удобства обслуживания.

При указании строковых аргументов для командлетов вы заключаете их в кавычки (New-Object 'System.Int32' или New-Object System.Int32

Заключение строковых аргументов в кавычки кажется намного более понятным при чтении кода, поэтому я бы включил их.

При написании функций и фильтров вы указываете типы параметров?

Только когда это необходимо, чтобы устранить неоднозначность для переводчика (что происходит). Если вы собираетесь попробовать и помещать типы во все, вы можете также написать и написать приложения для командной строки на C # (что не всегда плохо, но сводит на нет экономию времени, получаемую с помощью сценариев).

Вы пишете командлеты в (официальном) правильном регистре?

Вы должны . Я обычно делаю. Когда я поторопился, я, как было известно, немного расслабился, поскольку это не имеет синтаксического значения.

Для таких слов, как BEGIN ... PROCESS ... END, вы пишете их только в верхнем регистре?

Нет, это не Фортран. Я думаю, что большинство людей находят beginили Beginболее читабельным, чем BEGIN. Есть причина, по которой мы связываем все заглавные буквы с криками в сети, а выкрикивание самых обыденных частей программы ухудшает читабельность, обращая внимание на части, которые имеют наименьшее значение.

Руководящий принцип должен быть удобочитаемым. Скрипты по своей природе быстрые и грязные программы отклоняются от кода, предназначенного только для записи. Каждое ваше решение должно быть принято, чтобы вы и ваша команда могли понять сценарий в течение шести месяцев. Попытайтесь взять себя в руки, когда будете смотреть на свой код, и задать следующий вопрос: «Если бы я начал эту работу неделю назад (и поэтому не был действительно внушен в общую культуру), я бы нашел, как это написано, освещая или сбивает с толку?

Microsoft написала и опубликовала очень хороший набор рекомендаций по разработке командлетов

Выдержка:

В темах этого раздела приведены рекомендации по разработке, которые можно использовать для создания правильно сформированных командлетов. Используя общие функциональные возможности, предоставляемые средой выполнения Windows PowerShell, и следуя этим рекомендациям, вы можете разрабатывать надежные командлеты с минимальными усилиями и предоставлять пользователю единообразные возможности. Кроме того, вы уменьшите нагрузку на тестирование, поскольку обычные функции не требуют повторного тестирования.

В этой секции

• Требуемые руководящие указания по разработке
• Руководства по развитию
• Рекомендации по разработке рекомендаций

Эти рекомендации не ограничиваются каким-либо языком (в них не упоминается язык) и идеально применимы при написании командлетов в PowerShell.

Использование этих рекомендаций поможет вам написать понятные, доступные для обнаружения, пригодные для повторного использования и повторно используемые командлеты. Я считаю, что после создания нескольких модулей PowerShell следовать этим рекомендациям несложно, и это помогло мне стать лучшим разработчиком PowerShell. Этот навык можно использовать и при написании простых скриптов.

В качестве второго ответа; Вы можете использовать модуль PSScriptAnalyzer для проверки вашего кода.

Invoke-ScriptAnalyzer -Path .

Он основан на анализе кода с использованием набора правил. Это проверит дизайн кода и поможет вам обнаружить множество мелких проблем в вашем коде.

Мы включили его в наши сборки (мы используем сборки и закрытое хранилище для модулей), чтобы выявить проблемы с дизайном и качеством.

Если вам интересно, этот модуль также содержит модуль форматирования кода PowerShell (который может использовать несколько стилей), так что вы также можете использовать его для стандартизации макета кода.

Документы в ответе @ oɔɯǝɹ - хороший, хотя и несколько косвенный источник.

Если вы используете код Visual Studio, который планируется заменить устаревший PowerShell ISE, а затем установить расширение VS Code PowerShell , которое включает несколько параметров форматирования, которые хотя бы частично основаны на неофициальном руководстве по рекомендациям и стилю PowerShell . И VS Code, и расширение PowerShell управляются Microsoft, поэтому оно является настолько же официальным, сколь и неофициальным руководством.

Я не согласен со всем, что они заявляют. Например, я пришел из PHP, Java, C # и SQL, где точки с запятой ожидаются, если не требуется. Код выглядит неправильно для меня без них, поэтому я включаю их. Если бы это было, #requires SemicolonTerminatorя бы включил его в большинстве моих сценариев, чтобы мне не пришлось беспокоиться о пробелах, ломающих строку. Я ненавижу избегать возврата каретки и других VB-измов.

Остальные это мое мнение:

Использовать настоящее имя или псевдоним командлета?

Будь однозначным. Никогда не используйте псевдоним в сохраненном скрипте; даже псевдоним по умолчанию. Ничто не мешает пользователю изменять псевдонимы по умолчанию. Безопаснее предположить, что они не неизменны.

Укажите имя параметра командлета полностью или только частично (dir -Recurse против dir -r)

Опять же, будьте однозначны. Полные имена параметров имеют лучшую прямую совместимость. -rсегодня может быть однозначным, но ничто не мешает будущим версиям команды вводить новые параметры. Вы собираетесь использовать IDE (код ISE или VS). Хит Ctrl+ Spaceи автозаполнение этого параметра.

Обратите внимание, что ls -r это неоднозначно. -ReadOnlyэто еще один параметр Get-ChildItem.

При указании строковых аргументов для командлетов вы заключаете их в кавычки (New-Object 'System.Int32' или New-Object System.Int32

В общем, кавычки следует использовать только при необходимости (например, New-Object -TypeName 'System.Collections.Generic.HashSet[System.Int32]'использовать одинарные кавычки, когда это возможно, и только двойные кавычки, когда вам нужно инкапсулировать одинарные кавычки или нужно встраивать переменные.

При написании функций и фильтров вы указываете типы параметров?

Обычно я делаю это, если только мне не нужно принимать широкий спектр типов с одним и тем же параметром и не хочу писать отдельные наборы параметров.

Вы пишете командлеты в (официальном) правильном регистре?

Случай Паскаля. Да.

Для таких слов, как BEGIN ... PROCESS ... END, вы пишете их только в верхнем регистре?

Я видел заявления, операторы и конструкции языка , как Begin, If, ForEach, -NotInа также begin, if, foreach, -notin. Лично я предпочитаю строчные буквы и оставляю команды как регистр Паскаля, но они оба одинаково распространены.

Другие:

• Всегда указывайте параметры. Не полагайтесь на позиционный порядок. New-Object -TypeName System.Int32более New-Object System.Int32. Я не знаю, было ли это согласовано, но, опять же, похоже, что оно поддерживает общую идею «быть недвусмысленным».

• Если я пишу модуль, я использую стандартные глаголы, обозначенные Get-Verb. Однако этот список чрезвычайно узок, поэтому часто имена автономных сценариев для сценариев, которые будет запускать только я сам, не будут. Проблема с общим списком глаголов в том, что он стремится к Get-ScriptForSpecificPurposeNoNotThatOneTheOtherOne.ps1. Если я пишу сценарий, который извлекает определенные страницы из файла PDF, я не буду его называть Get-ExtractedAccountPDFPages.ps1. Я звоню это Extract-AccountPDFPages.ps1. Меня не волнует возможность обнаружения сценария, который запускается как сама программа и не предназначен для модульности по самой своей природе.

• Нарушайте правила, когда это становится более читабельным, более конкретным или более понятным.

За прошедшие годы появилось множество способов написания многословных имен для переменных, функций и т. Д.

PROGRAMFORSORTINGLOTSOFTHINGS трудно читать.

PROGRAM_FOR_SORTING_LOTS_OF_THINGS немного проще.

program_for_sorting_lots_of_things еще проще.

ProgramForSortingLotsOfThings устраняет подчеркивание и поддерживает удобочитаемость. Powershell делает это по большей части.