Чи є відомі умови кодування PowerShell?

Чи є чітко визначені умови під час програмування в PowerShell?

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

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

Схоже, що в MSDN не вистачає документа з умовами кодування для PowerShell, тоді як такий документ існує, наприклад, для C #.

@Robert Harvey посилався на кілька хороших офіційних посилань. Як менш офіційний документ, мої думки були б:

Використовувати справжнє ім'я командлета або псевдонім?

Псевдонім використовуйте лише тоді, коли він зрозуміліший за повне ім’я. Наприклад, я думаю, що більшість людей знайдуть dirабо lsзрозуміліші в сценарії, ніж Get-ChildItemна основі попереднього досвіду (наприклад, кожен, хто пише сценарій PowerShell, має один із цих двох разів у пакетних сценаріях DOS або сценаріях Unix).

Вкажіть назву параметра командлет повністю або лише частково (dir -Повторити проти dir -r)

У сценарії я б повністю прописав ім'я, тому що (на відміну від вищевказаного прикладу) я не можу придумати час, коли коротший перемикач насправді був би більш чітким, ніж його написання. Коротші назви комутаторів - це збереження набору тексту. У командному рядку це обов’язково. У сценарії додаткові натискання клавіш цілком варті того, щоб читати і ремонтувати.

Вказуючи рядкові аргументи для командлетів, ви додаєте їх до лапок (New-Object 'System.Int32' проти New-Object System.Int32

Включення рядкових аргументів у лапки здається набагато зрозумілішим при читанні коду, тому я б включив їх.

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

Тільки тоді, коли є необхідність зробити це для усунення неоднозначності для перекладача (що і відбувається). Якщо ви збираєтеся спробувати ввести типи на все, ви можете також запустити і написати додатки командного рядка C # (що не завжди погано, але це заперечує економію часу, яку ви отримуєте шляхом написання сценаріїв).

Ви пишете командлети в (офіційному) правильному відмінку?

Ви повинні . Я зазвичай так роблю. Коли я поспішав, я, як відомо, був трохи розслабленим у випадку, оскільки це не має синтаксичного значення.

Для таких ключових слів, як ПОЧАТОК ... ПРОЦЕС ... КІНЦЕ ви пишете їх лише в великих літерах?

Ні. Це не FORTRAN. Я думаю, що більшість людей знаходять beginчи можна Beginчитати, ніж BEGIN. Є причина, по якій ми пов'язуємо всі шапки з криками в Інтернеті та криками самих мирських частин програми, перешкоджає читанню, привертаючи увагу до найменш важливих частин.

Основним принципом має бути читабельність. Сценарії, за своєю суттю як швидкі та брудні програми, орієнтуються на код лише для запису. Кожне ваше рішення повинно бути прийняте для того, щоб ви та ваша команда все-таки зрозуміли сценарій протягом шести місяців. Спробуйте вийняти себе з власного взуття, дивлячись на свій код, і задайте це запитання: "якби я розпочав цю роботу тиждень тому (і так насправді не було присвоєно загальній культурі), я знайшов би спосіб, як це написано освітлюючим чи заплутано? "

Microsoft написала та опублікувала дуже хороший набір Керівних принципів розвитку Cmdlet

Витяг:

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

У цьому розділі

• Необхідні вказівки щодо розвитку
• Сильно заохочені настанови щодо розвитку
• Керівні рекомендації щодо розвитку

Ці вказівки не обмежуються жодною мовою (в них не згадується мова), і цілком застосовні під час написання Cmdlets в PowerShell.

Використовуючи ці вказівки, ви допоможете написати чіткі, відкриті, корисні та використані Cmdlets. Мені здається, що після створення декількох модулів PowerShell слідувати цим рекомендаціям не важко, і це допомогло мені стати кращим розробником PowerShell. Цей навик можна використовувати і під час написання простих сценаріїв.

Як друга відповідь; ви можете використовувати модуль PSScriptAnalyzer для перевірки свого коду.

Invoke-ScriptAnalyzer -Path .

Він заснований на аналізі коду з використанням набору правил. Це підтвердить дизайн коду та допоможе виявити багато маленьких проблем у вашому коді.

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

Якщо вас цікавить, цей модуль також містить форматформа коду PowerShell (який може використовувати декілька стилів), тому ви можете використовувати його і для стандартизації макета коду.

Документи у відповіді @ oɔɯǝɹ є хорошим, хоча дещо дотичним джерелом.

Якщо ви використовуєте код Visual Studio, який планується замінити старіший PowerShell ISE, а потім встановіть розширення VS Code PowerShell , яке включає кілька варіантів форматування, які, принаймні частково, базувалися на неофіційному посібнику з найкращих практик та стилю PowerShell . І VS Code, і розширення PowerShell управляються корпорацією Майкрософт, тому це приблизно так само офіційно, як і неофіційне керівництво.

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

Решта з них - моя думка:

Використовувати справжнє ім'я командлета або псевдонім?

Будьте однозначними. Ніколи не використовуйте псевдонім у збереженому сценарії; навіть псевдонім за замовчуванням. Ніщо не заважає користувачеві змінювати псевдоніми за замовчуванням. Безпечніше вважати, що вони непорушні.

Вкажіть назву параметра командлет повністю або лише частково (dir -Повторити проти 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, 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 робить це здебільшого.