この記事は、PowerShell Advent Calendar 2017 3日目の記事です。

新しい言語を触るときに気になるのが、その言語はどのように書くことを意図しているのかです。私が触ってきた言語の多くは「その言語の考えの基本」となるものを持っており、コーディングガイドライン上でもそれを明示していることが多いように思います。

PowerShell はどうなのでしょうか? 今回はPowerShell ではどのようなコーディングスタイル (本記事ではコーディング規則も同じ意味で用います)で書くといいのかを考えてみたいと思います。

思いのほか記事内容がながくなってしまったので、結論だけ見たい方はまとめをどうぞ

※ 決してこの記事の内容が絶対正しいと思っていません。みなさんが書いていく中でどうすればいいのか、と思ったときの良いヒントになることを願っています。

軽い記事を書くつもりが大きくなりすぎたので、コーディングスタイルは主語が大きすぎということを感じました。補完しあう内容となる APIデザインも5日目に書きました。

tech.guitarrapc.com

目次
コーディングスタイル
- 他言語の例 : C#
- 他言語の例 : Swift
PowerShell のコーディングスタイル
PowerShell Cmdlet を C# で書く場合のコーディングスタイル
余談 : PowerShell Core のコーディングスタイル
PowerShell Scipt で書く場合のコーディングスタイル
- PowerShell scripting best practices
- PowerShellPracticeAndStyle
余談 : PowerShell のインデントスタイル
余談 : ドキュメントフォーマッター
まとめ
- C# で書く Cmdlet の Coding Style
- PowerShell で書く Funcion の Coding Style

コーディングスタイル

ここでは言語を設計した側が意図している、あるいはコミュニティの中で共通認識として持っているものを指して考えたいと思います。

各開発チームごとにルールは別に設けられることもあるので、そこには触れません。言語として意図している、言語的にこうするといいとコミュニティの合意が取れている例と考えると読みやすいのでしょうか。優しい世界の優しいやり方に努めたいと思います。

さて、PowerShell に入る前に他の言語の例から見てみましょう。いろんな言語で、それぞれの考えがあって素敵です。

他言語の例 : `C#`

Microsoft が出しているコーディングガイドラインがあります。そこには次のようにコーディング規則の意義を説明しています。

C# 言語仕様では、コーディング標準は定義されていません。ただし、このトピックのガイドラインは、サンプルおよびドキュメントを開発するためにマイクロソフトによって使用されます。コーディング規則には、次の目的があります。コードの見た目が統一されるため、コードを読むときに、レイアウトではなく内容に重点を置くことができます。これにより、経験に基づいて推測することで、コードをより迅速に理解することができます。コードのコピー、変更、および保守が容易になります。コーディング規約により、C# のベストプラクティスがわかります。

C# のコーディング規則 (C# プログラミングガイド) | Microsoft Docs *1

合わせて .NET Framework の API デザインにおける名前付けのガイドラインもあります。

Framework デザインガイドライン

名前付けのガイドライン *2

.NET Framework 、特に C# を書き始める、どんなガイドラインで書けばいいか困ったなぁという時には .NETのクラスライブラリ設計 が非常に良い内容だと思っています。今は書籍が絶版で Kindle 版のみです。内容はAPIデザインガイドという意味で、他言語を扱うときにも参考になっていると感じます。

.NETのクラスライブラリ設計

C# のインデントスタイルは、 Allman Style で紹介されています。

他言語の例 : `Swift`

Swift にも、API Design Guidelines としてガイドラインがあります。

swift.org

Swift がGithub上でオープンに開発される中で、いくつかの Proposal は検討の末リジェクトされていますが、それら理由にはガイドラインからの引用も多く見られます。徹底されているの素晴らしいです、ね。

Github/Swift - Commonly Rejected Changes

qiita.com

特に、「明瞭さは簡潔さよりも重要です」としたガイドラインは、Swift を書く上で自然と意識します。コミュニティの発信する情報も、多くがガイドラインに沿う努力がなされているように思います。

Clarity is more important than brevity. Although Swift code can be compact, it is a non-goal to enable the smallest possible code with the fewest characters. Brevity in Swift code, where it occurs, is a side-effect of the strong type system and features that naturally reduce boilerplate.

Swift のインデントスタイルは、 K&R 1TBS (OTBS) で紹介されています。このあたりの記事でもその辺が紹介されていますね。

Swift bracing

PowerShell のコーディングスタイル

さて、他言語の例をみたところで、PowerShell にも同様のガイドラインはあるのでしょうか? 答えは「あります」。ただ、PowerShell は Cmdlet(C#) と Script(PowerShell) として記述ができる*3ため長くなってしまいます。

そこで本記事においては、C# で Binary Cmdlet を記述する場合、PowerShell としてFuncion を記述する場合の2面から見てみましょう。

PowerShell Cmdlet を C# で書く場合のコーディングスタイル

まずは、PowerShell の Cmdlet = C# で記述するものとして見てみましょう。このガイドラインは、MSDN にて Microsoft から公開されています。

https://msdn.microsoft.com/en-us/library/dd878270.aspx

中身は、3つに分かれています。

Required Development Guidelines : 必須とするガイドライン
Strongly Encouraged Development Guidelines : 守ることを強く要請するガイドライン
Advisory Development Guidelines : アドバイスとしてのガイドライン

順にみていきましょう。

Required Development Guidelines

必須とするガイドラインです。

https://msdn.microsoft.com/en-us/library/dd878238.aspx

Design Guidelines と Coding Guidelines がありますが、Coding Guidelines のみ触れます。

(Coding Guidelines) Derive from the Cmdlet or PSCmdlet Classes (RC01)

PowerShell Cmdlet を C# で書くときに Cmdlet 型か PSCmdlet 型を継承できます
- Cmdlet の .NET Framework からの呼び出しの自由さよりも、PSCmdletのRunSpace内での実行を推奨しています
- ここは若干微妙で、テストしやすさや Windows PowerShell Runtime と Core Runtime のずれがあるので今後の変更もあるかもしれません
また Cmdlet は public クラスである必要があります

(Coding Guidelines) Specify the Cmdlet Attribute (RC02)

Cmdlet には属性でどのように使うかを表明しましょう
verb-and-noun 表明により、公開するクラス名とCmdlet命名規則のずれをカバーできます。C# はクラスを PascalCase としていて、PowerShell はVerb-Noun ですからね！
デフォルトパラメータセットの表明やShouldProcessの表明もここで可能です

(Coding Guidelines) Override an Input Processing Method (RC03)

PowerShell Cmdlet は入力を3つのプロセスを通して処理します。Begin, Process, End です。これは良く説明されているので、さくっと紹介のみにとどめます
Cmdlet.BeginProcessing
- This method is called one time, and it is used to provide pre-processing functionality
Cmdlet.ProcessRecord
- This method is called multiple times, and it is used to provide record-by-record functionality
Cmdlet.EndProcessing
- This method is called one time, and it is used to provide post-processing functionality

(Coding Guidelines) Specify the OutputType Attribute (RC04)

OutputType属性を用いるといいでしょう
この属性を公開することで、パイプラインの先に型が伝搬します。しないと? Object になって、型が伝わらずインテリセンスが絶望的なことになります
ただ、PowerShell の Output は関数の返戻値型を強制しないため、ずれることがあるので注意です

(Coding Guidelines) Do Not Retain Handles to Output Objects (RC05)

Cmdlet は、WriteObject メソッドで出力をパイプラインに渡すのですが、このメソッドに渡す際にオブジェクトを内部で保持しないようにしましょう。ふつうにリークしたり予期しないエラーの原因になります。だめ

(Coding Guidelines) Handle Errors Robustly (RC06)

エラーハンドルです
処理がこれ以上続行できない場合は、ThrowTerminatingErrorメソッドでエラーを返しましょう
- もし例外が Cmdlet で取得できず漏れてしまった場合、PowerShell ランタイムがターミネートされます。しかもエラー情報である ErrorRecord オブジェクトの情報が欠落するので意味不明な状況になって使い心地が最悪になります
もし処理ターミネートされるエラー出ない場合、ErrorRecord　を WriteErrorメソッドに渡してハンドルしましょう
例外の表明に使う ErrorRecord は、.NET GGramework のデザインガイドラインに沿って、すでにあるException で表明できるならそれを使いましょう。もし新規に作る必要があるなら、Exception型を継承する定石に乗ることを推奨します
- また、Errorrecord は、エラーをグルーピングする ErrorCategory の提供してください
Cmdlet がスレッドを生成して、そのスレッドでエラーを起こした場合、PowerShell は例外をキャッチせずPowerShellプロセスをターミネートします。PowerShell でマルチスレッド処理を書くのが苦しい原因になっていますね
もしデストラクタでUnhandled Exception が生じた場合は、PowerShell は例外をキャッチせずPowerShellプロセスをターミネートします。Dispose でUnhandled Exception を起こした時も同様です

(Coding Guidelines) Use a Windows PowerShell Module to Deploy your Cmdlets (RC07)

Cmdlet の提供は Module で
- SnapIn とか忘れましょう
- 私自身 Moduleしか書きません。実際、PowerShell Get でのモジュール提供がインフラとして浸透した今、Module 以外で提供するのはエコシステムからも外れているのでつらいでしょう

Strongly Encouraged Development Guidelines

守ることを強く要請するガイドラインです。

https://msdn.microsoft.com/en-us/library/dd878270.aspx

これもDesign Guidelines と Coding Guidelines がありますが、Coding Guidelines のみ触れます。

(Coding Guidelines) Coding Parameters (SC01)

Parameter と読んでいるものは、public Property に[Parameter()] 属性をつけたものが該当します。パラメータは、Static Member である必要がありません。

詳細は、Parameter Attribute Declaration で説明されています。

Support Windows PowerShell Paths
- PSPath のような Normalize されたものを示しています
- Path は String 型で表明してください
- Path は、Alias として PSPath を与えてください。[Alias("PSPath") ですね
- また、Path はワイルドカード(*) をサポートしてください
  - もしワイルドカードをサポートしない場合、LiteralPath パラメータとして用意しましょう
  - 個人的には、Path はパスワイルドカードのハンドルは、パス名に [ などのもじが入っていた時に崩れやすいため、LiteralPath のほうが意図した挙動にはしやすいかと思います
  - が、Path のほうが扱いやすいのも事実なので、提供側がどんな利用をするか手触りで選べばいいと思います
Support Wildcard Characters
- もし可能であれば、パラメータはワイルドカード入力をサポートするといいでしょう
- Process 名を探すときにGet-Process git* などのように、ワイルドカードサポートは利便性を大きく向上します
- ワイルドカード入力をサポートしても、出力は複数になるかは一致するとは限りません。適切に扱ってください。例えば、Set-Location はパスにワイルドカードを受け付けますが、移動は一度だけです
Define ObjectMembers to Be Used as Parameters
- もし Cmdlet のためのオブジェクトを用意する場合、そのオブジェクトを Parameter として受け入れられるようにすることを考えてください
- また、独自の型で出力する場合は、PowerShell がユーザーに表示する際やパイプラインでメンバー渡すのに向いていないことがあります。この場合は、custom Types.ps1xml を作成して用意するといいでしょう。その場合の名前は、<Your_Product_Name>.Types.ps1xml が推奨されます
  - 例えば、FileInfo を表現するときにMode という ScriptProperty を用意してわかりやすくするなどが考えられます
  - ってありますが、つくらないですねぇ。私は。Cmdlet で用意するにしても、.NET で表現できた方が好きなので。Length の代わりに Count とかもあんまり好きじゃなかったり
Implement the IComparable Interface
- IComparable Interface を用意することで、データ処理が楽になります
  - わたしは作りません。いるケースをかかないっていうのもありますがPowerShell でのデータ処理を複雑に行うことはないですねぇ
Update Display Information
- <YourProductName>.Format.ps1xm を用いることで、表示を望む形に定義できます
  - 私は書かないです

(Coding Guidelines) Support Well Defined Pipeline Input (SC02)

Implement for the Middle of a Pipeline
- Pipeline の途中でも動くように書くとパイプラインフレンドリーです。たとえば Get-Process の結果を受けるように書くときなどです
- 個人的にも、パイプラインは都度ストリーム処理なので速度という意味ではパフォーマンスは不利ですが、メモリ効率性は高くPowerShellっぽくパイプラインでつないでさくっとデータ処理を書けるという意味では「書くのが楽」なスタイルなのでおススメです
Support Input from the Pipeline
- ではどうすればパイプラインを受けられるのかですが、Parameter に、ValueFromPipeline やValueFromPipelineByPropertyName 属性を足してください
Support the ProcessRecord Method
- ストリームを都度処理することがパイプラインの特徴です
- そこれで、ProcessRecord メソッドをオーバーライドすることで、ストリームからの都度入力を操作できます

(Coding Guidelines) Write Single Records to the Pipeline (SC03)

Pipeline はストリーム処理をすることに良さがるので、出力を都度シングルレコードで WriteObject メソッドで書き出すといいです
バッファリングして出力をためたりするのは、一度立ち止まって考えてからのほうがいいです
- もしバッチ処理的に、出力をまとめた吐く場合は、System.Managemet.Automation.Cmdlet.WriteObject(System.Object,System.Boolean) の台に引数に trye を渡しましょう
- 私自身、時々ためる処理を書いていますが、原則はパイプラインでの処理を速やかに後続に渡すようにしています

(Coding Guidelines) Make Cmdlets Case-Insensitive and Case-Preserving (SC04)

Windows PowerShell 自体が case-insensitive なため、処理もそれに従いましょう

Advisory Development Guidelines

アドバイスとしてのガイドラインです。

https://msdn.microsoft.com/en-us/library/dd878291.aspx

Design Guidelines と Coding Guidelines がありますが、Coding Guidelines のみ触れます。

(Coding Guidelines) Follow Cmdlet Class Naming Conventions (AC01)

Define a Cmdlet in the Correct Namespace
- 適切な名前空間におきましょう
- 名前空間は、.Commands をつけるといいです
  - おっと、そういえばですね
Name the Cmdlet Class to Match the Cmdlet Name
- Cmdlet のクラス名は、<Verb><Noun><Command> と命名するといいです
  - たとえば、Get-Process Cmdlet なら、クラス名は、GetProcessCommand となります

(Coding Guidelines) If No Pipeline Input Override the BeginProcessing Method (AC02)

もしパイプラインからの入力を受け付けない 場合、BeginProcessing メソッドをオーバーライドして処理を書きましょう
パイプラインで動く場合、初めのCmdlet が実行されたときに、他のパイプラインの処理が動く前に呼び出されます
- この begin の動きが、一番混乱を生みやすいですね

(Coding Guidelines) To Handle Stop Requests Override the StopProcessing Method (AC03)

StopProcessing メソッドを可能であればオーバーライドしてください。これによって、Stop信号を制御できるようになります
たとえば、長時間実行するようなCmdlet の場合なんですが、これまともに機能している例をあんまりみないんですよね。Job などの仕組みです

(Coding Guidelines) Implement the IDisposable Interface (AC04)

PowerShell は、EndProcessing を必ずしも呼びません。例えばパイプラインの途中でエラーが出たときとかですね
そこで、もし Dispose が必要なリソースを用いる場合は、IDisposable を実装して、明示的にDispose を呼び出してください
- ここださいんですよねぇ。Cmdlet 書いていてつらい部分です

(Coding Guidelines) Use Serialization-friendly Parameter Types (AC05)

もしリモート先で動作するような Cmdlet を書く場合、Seriablize しやすくしましょう。以下がフレンドリーな型です
- Primitiveな型
  - Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32, and UInt64
  - Boolean, Guid, Byte[], TimeSpan, DateTime, Uri, and Version
  - Char, String, XmlDocument
- Built-in 型
  - PSPrimitiveDictionary
  - SwitchParmeter
  - PSListModifier
  - PSCredential
  - IPAddress, MailAddress
  - CultureInfo
  - X509Certificate2, X500DistinguishedName
  - DirectorySecurity, FileSecurity, RegistrySecurity
- 他いくつか
  - SecureString
  - Containers (lists and dictionaries of the above type)

(Coding Guidelines) Use SecureString for Sensitive Data (AC06)

センシティブなデータは、SecureString 使いましょう

余談 : PowerShell Core のコーディングスタイル

PowerShell は、現在 PowerShell Core が OSS として開発されています。これは C# で書かれています。そのため、この PowerShell 本体で用いられている C# のコーディング規則が公開されています。

C# Coding Guidelines

基盤実行のため、わかりやすさとパフォーマンスに重点が置かれていることが見て取れます。

Naming Conventions

メソッドの名前付けに関して、PowerShell自体の原則である Verb-Noun に合わせてLoadModule などのような - 抜きの名前付けを推奨しています
private field に関して Instance Filed のPrefixとして、_、Static Field は s_ (加えて readonly を用いる場合 static readonly という順番)、Thread Static Field は t_ という命名を示しています
- Prefixは、C# の一般的な名前付けの指針とはずれがあります。https://msdn.microsoft.com/ja-jp/library/ms229012.aspx
- X DO NOT use a prefix for field names. For example, do not use "g" or "s" to indicate static fields.

Layout Conventions

C# 同様の Allman Style であることが見て取れます。

Avoid more than one blank empty line at any time
Avoid trailing spaces at the end of a line
Braces usually go on their own lines, with the exception of single line statements that are properly indented

Performance Considerations

LINQ のゴミをさけること、for/foreach の選択に関して触れています。

Avoid LINQ - it can create lots of avoidable garbage. Instead, iterate through a collection directly using for or foreach loop
Between for and foreach, for is slightly preferred when you're uncertain if foreach allocates an iterator

他にも、メモリアロケーションを避けるためのUtil として定義された static field の利用や boxing の回避のための Generics の利用など細かな内容が続きます。

Best Practices

この中で興味深いのは、C# の新しいシンタックスの利用は推奨されていることです。ただし既存のコードに適用する場合は、別のPR にすることを言っています。コード公開時のコードはずいぶんと古い書き方に感じたことを覚えています。

Use of new C# language syntax is encouraged. But avoid refactoring any existing code using new language syntax when submitting a PR as it obscures the functional changes of the PR. A separate PR should be submitted for such refactoring without any functional changes.

PowerShell Scipt で書く場合のコーディングスタイル

PowerShell Team からのものと、コミュニティからのものが公開されています。

PowerShell Team

https://blogs.technet.microsoft.com/pstips/2014/06/17/powershell-scripting-best-practices/

コミュニティ

github.com

また、別にPowerShell DSC のコーディングスタイルとしてHighQualityModuleGuidelines が公開されています。これは Module 特に DSC としてに注視しているため、ここでは扱いません。

github.com

PowerShell scripting best practices

PowerShell Team Blog の内容です。

ドキュメントコメントを用いて、name, date, author, purpose and keywordsの記述をしましょう
可能な限りコメントを書きましょう。ただし行き過ぎないレベルで
#Requires タグを用いて、サポートする PowerShell ミニマムバージョンを明示することで、後からわかりやすくしましょう
Set-StrictMode -Version Latest コマンドを使って、初期化されていない変数アクセス、存在しないプロパティやオブジェクトアクセスを防ぎましょう
シンプルだが意味のある変数命名をしましょう。camelCase がベストプラクティスです。($serviceName など)
1. camelCase はローカル変数のみ指しています。Parameter は指していません
スクリプトの上部に、ユーザー定義変数を記述しましょう
可能であれば、CodeSigning を使います。(RemoteSigned / AllSigned を Execetion Policy に使います)
Alias は使わないように。フルCmdlet名、かつパラメータを明示します
backticks は使用をさけます。パイプライン | や Splatting を活用します
Filter left, format right にします
.exe 拡張子を外部コマンド呼び出し時につけます。sc ではなく sc.exe という感じです
$ErrorActionPreference = "SilentlyContinue" でパイプラインのエラーを消さないように。try. catch, finally や trap で構造的に制御します
PowerShell 挙動制御変数を使って、挙動を変えないようにします。$ConfirmPreference などです
CmdletBinding を用いて、-WhatIf, -Verbose, -Debug をサポートしましょう
Advanced Functions をサポートしましょう
Verb-Noun 形式で表示します。また、標準に用意されたVerb(動詞)を使いましょう
パラメータは汎用的な命名にし、必要なら初期値を入れます。(Server より ComputerName が望ましい)
1 Function = 1 動作にします。1動作をよく取り扱いましょう。(Linux と同様ですね)
関数は、常にオブジェクトを返して、文字列を返すことは避けます
return キーワードの利用は避けます。パイプラインの中で自動的に返されます
1. この挙動は結構悩ましいのお気をつけて
Write-Output はWrite-Host より望ましいです。なぜなら、Write-Host はホストに書き出しますが、パイプラインに書かないからです
Comment Base help を用いましょう
接続を確認するときは、Test-Connection を -Quiet スイッチで使いましょう
スクリプトは、書式をきれいにそろえましょう
1. といいつつ、ここで書式の明示はありません
どこから実行しても動くようにしましょう。$myInvocation.MyCommand.Pathや$PSScriptRoot が PowerShell 3.0 以降で利用できます
関数はテストしましょう。昇格やバージョン、存在有無のテストを含みましょう
Production リリース前にテスト環境でテストしましょう
Module や PowerShellGet を使って再利用しましょう
Script を、作る、書く、使う、メンテナンス、レビューするパイプラインは用意しましょう
こんな構成がシンプルです
1. #Requires を書く
2. パラメータを定義
3. 関数を書きます
4. 変数を定義します
5. コードを実行します
6. コメントベースヘルプを用意します

PowerShellPracticeAndStyle

コミュニティの共通認識になっている、Style Guideについて触れます。これは Python コミュニティを見習ってできた流れです。

The PowerShell Style Guide

いかについて触れられています。

Code Layout and Formatting
Function Structure
Documentation and Comments
Readability
Naming Conventions

(Code Layout & Formatting) Maintain consistency in layout

このガイドラインを強制するつもりがなく、一貫性を重視しています。1行の長さや行の数など、個人の主張があればどうぞ。という立場が貫かれています。

それを前提に参考にしてください。

(Code Layout and Formatting) Capitalization Conventions

次の用語の意味で読み進めてください。

lowercase - 全部小文字、単語分離なし
UPPERCASE - 全部大文字、単語分離なし
PascalCase - 各単語の初めの一文字だけ大文字
camelCase - 最初の単語を除く各単語の初めの一文字だけ大文字

PoweShell は、Case-Insensitive なので大文字、小文字を区別しません。しかし、PowerShell が .NET Framework でできていることから、次のルールに沿っています。

Capitalization Conventions - Framework Design Guidelines | Microsoft Learn

PowerShell は、public なアクセスのものはすべて PascalCase を使っています
- Function, Cmdlet 名
- Class
- enum
- Attribute(属性)名
- パブリックフィールドやパブリックプロパティ
- グローバル変数
- グローバル定数
- PowerShell のパラメータも.NET Class のプロパティなので PascalCase とします
PowerShell のキーワードは、lowerCase で表現します
- foreach や dynamicparam
- -eq などのオペレータ
コメントベースヘルプは UPPERCASE で示します
- .SYNOPSIS
- .DESCRIPTION
- 他
Function(関数)名は、Verb-Noun 形式にします。また、Verb/Noun は、PascalCase とします
特殊な2文字はキャピタルで示します
- 例えば$PSBoundParameters や Get-PSDrive の PS がそうです
- Capitalization Conventions - Framework Design Guidelines | Microsoft Learn に沿ってください
関数やモジュール内の変数は camelCase とします。こうして、パラメータと区別しますが、ただの好みによります
共有変数としての $Script:PSBoundParameters などはスコープ名を付けて明示します
特殊な2文字を含むローカル変数は、adComputer などのように両方 lowercase にします

(Code Layout & Formatting) Always Start With CmdletBinding

必ず関数は、[CmdletBinding()] param() で開始します
- いわゆる AdvancedFunctions ということです
- 必要に応じて、begin / process / end の各ブロックの1つは外してもいいでしょう
- Pipeline 入力を受け取ることを考えてください
Open Brace { は同じ行に書きます。*4
Close Brace } は、自分音表に書きます。*5

(Code Layout & Formatting) Indentation

4スペースインデントを用います。(ソフトタブ)
- これは PowerShell ISE の挙動に沿っています
- 行を並べる時には、文字列を縦にそろえることを検討してください
  - 個人的に、アラインはIDEがしないならしないですが、DSC のような宣言型では有用に思える時があります

(Code Layout & Formatting) Maximum Line Length

1行115 文字以内に押さえます
- PowerShell コンソールのデフォルトが120文字であることから示されています
行を抑えるためには、Splatting が有用です

(Code Layout & Formatting) Blank lines

関数やクラスは、2行あけます
クラス内のメソッドは1行あげます
関連するワンライナーでは、空行は省略されることが多いです
関数の集合や処理をまとめるのに、控えめに空行を使うのもいいでしょう
パラメータに渡すときは、: よりも明示的に渡しましょう
- X : $variable=Get-Content $FilePath -Wai:($ReadCount-gt0) -First($ReadCount*5)
- O : $variable = Get-Content -Path $FilePath -Wait:($ReadCount -gt 0) -TotalCount ($ReadCount * 5)

(Code Layout & Formatting) Spaces around special characters

カンマやセミコロン、{、} の後に空白スペースをいれます
かっこや[] の中に余計な空白スペースが入らないようにします
$( ... ) や{ ... } は、中の前後にスペースを1つ入れて読みやすくします
- 逆に外にスペースは読みやすさのため「いりません」

(Code Layout & Formatting) Avoid using semicolons (;) at the end of each line.

PoweShell はセミコロン; を使えますが必須としません。編集やコピペされることを考え、いらないなら点けないようにしましょう
同様に Hashtable の定義時も; はいりません

(Function Structure) Functions

return キーワードの利用は避けます
シンプルな巻子うを定義するときは、関数名とパラメータにスペースを空けます
- function MyFunction ($param1, $param2)

(Function Structure) Advanced Functions

命名は <verb- から始まるようにします
Noun (名詞) 部分は、1つ以上を結合した単語でPascalCase 、単数形書きます
return キーワードの利用は避けます
Process {} でのみ値を返し、Begin {}、End {} では返さないようにします。これをしないと、パイプラインのメリットが損なわれます
- return を用いないのはこの意味で意味が通っています

(Function Structure) Always use CmdletBinding attribute.

[CmdletBinding()] を必ず用います

(Function Structure) Always have at least a process {} code block if any parameters takes values from the Pipeline.

Pipeline からの入力があるなら、process {} ブロックを用意します

(Function Structure) Specify an OutputType attribute if the advanced function returns an object or collection of objects.

返戻値の型を [OutputType(T)] 属性で明示します。日うように応じて、パラメータセットとともに明示します
- [OutputType([<TypeLiteral>], ParameterSetName="<Name>")]
- [OutputType("<TypeNameString>", ParameterSetName="<Name>")]
  - 私は、[OutputType([<TypeLiteral>]) 形式がインテリセンス補完効くので好みです

(Function Structure) When a ParameterSetName is used in any of the parameters, always provide a DefaultParameterSetName in the CmdletBinding attribute.

ParameterSetName を用いる場合は、[CmdletBinding()] に DefaultParameterSetName を明示します

(Function Structure) When using advanced functions or scripts with CmdletBinding attribute avoid validating parameters in the body of the script when possible and use parameter validation attributes instead.

Script 内部ではなく、パラメータの属性でバリデートを検討します

(Documentation and Comments) Comment

常に更新しましょう
英語でコメント書きます
「何をしているか」ではなく「なぜ」を意識して書きます
- うまく PowerShell らしく書くと、それ自体が説明しているように表現できます

(Documentation and Comments) Block comments

一行ごとにコメントをつけたりはしないように
- そういう場合は、ブロックコメントを検討してください
また、コメントが長い場合は、<# ... #> で複数行のコメントを表現できます

(Documentation and Comments) Inline comments

気が散るためあまり好まれません
が、もし短いコードに説明を要する状況ではやる価値があります
2文字以上コードとスペースを挙げて表現してください
また同じブロックの他のinline comment 行と頭をそろえると読みやすいでしょう

(Documentation and Comments) Documentation comments

Comment-based は、クラスの説明ではなく「何をする関数なのか」を書いてください
- 必要以上に強い言葉は避けます
- 短い説明に徹します
- だれかに印象付けるために書いているわけではなく、どう使えばいいかを伝えるために書くのです
- 外国語を書く場合、とくにシンプルな言葉でシンプル文で書くと、よりネイティブには意味が伝わります
- 必要十分を目指しましょう
書く場所は、関数の上ではなく中に書きましょう
- コメントの更新を意識づけるため、末尾より、頭がいいでしょう
- NOTES に詳細を書きます
- Synopsisに概要を書きます
- パラメータにコメントを書きます
  - 可能なら .PARAMETER に書きます
  - ただ、コード上に書いた方が良く更新される経験則があります
- .EXAMPLE に利用例を示します

(Documentation and Comments) DOC-01 Write comment-based help

関数には毎度書きましょう。

function get-example {
    <#
    .SYNOPSIS
        A brief description of the function or script.

    .DESCRIPTION
        A longer description.

    .PARAMETER FirstParameter
        Description of each of the parameters
        Note:
        To make it easier to keep the comments synchronized with changes to the parameters, 
        the preferred location for parameter documentation comments is not here, 
        but within the param block, directly above each parameter.

    .PARAMETER SecondParameter
        Description of each of the parameters

    .INPUTS
        Description of objects that can be piped to the script

    .OUTPUTS
        Description of objects that are output by the script

    .EXAMPLE
        Example of how to run the script

    .LINK
        Links to further documentation

    .NOTES
        Detail on what the script does, if this is needed

    #>

(Readability) READ-01 Indent your code

インテンドは答えがありません。ただし、Script ではなくPoweShell に解釈させたときに結果が異なることがあります
以下は、エラーが出ません

if ($this -gt $that) {
    Do-Something -with $that
}

以下はエラーがでます

if ($this -gt $that)
{
    Do-Something -with $that
}

構成要素をインテンドに収めるのがいいでしょう

ForEach ($computer in $computers) {
    Do-This
    Get-Those
}

(Readability) READ-02 Avoid backticks

Backticks ` は避けます
コミュニティは、あなたがBackticks を行継続 として使っていると感じます
- しかし読みにくい、見落としやすい、ミスタイプしやすい傾向にあります
- また Backticks の後ろにスペースを入れると動かなくなります

Get-WmiObject -Class Win32_LogicalDisk `
              -Filter "DriveType=3" `
              -ComputerName SERVER2

このような問題を引き起こしやすいため、テストやデバッグも難しくなる傾向にあります
代替としてこのような Splatting を使うといいでしょう

$GetWmiObjectParams = @{
    Class = "Win32_LogicalDisk"
    Filter = "DriveType=3"
    ComputerName = "SERVER2"
}
Get-WmiObject @GetWmiObjectParams

決して Backticks は嫌われていませんが、不便なことがあるので使う必要がないようにするといいでしょう

(Naming Conventions) Naming

短縮した名前をコマンドやパラメータに用いるより、明示的な名前付けが好まれます
Expand-Alias を使うことで、いくつかを修正できますが、問題をなくすことは難しいでしょう

(Naming Conventions) Use the full name of each command.

PowerShell を使う中でフル名を学びますが、Alias は1つによって違います。(Linux ユーザーにとっての ls は、DOS ではdir です)
もし共有スクリプトの場合、汎用的に知られている名前がいいでしょう
- ボーナスとして、Github ハイライトがかかりますよ

# Do not write:
gwmi -Class win32_service

# Instead write:
Get-WmiObject -Class Win32_Service

(Naming Conventions) Use full parameter names.

PowerShell には多くのコマンドがあるため、全コマンドを把握することはできません
パラメータ名を省略せずフルに書くことで、読む人がコマンドに詳しくなくても伝えることができるでしょう
また、不要なパラメータセットにまつわるバグを避けることができます

# Do not write:
Get-WmiObject win32_service name,state

# Instead write:
Get-WmiObject -Class win32_service -Property name,state

(Naming Conventions) Use full, explicit paths when possible.

省略パスを用いないようにします。基本的に . や .. が有効に機能するのは、特定のパスにいる時だけです
.NET メソッドが [Environment]::CurrentDirectory を使い PowerShell の現在パスを尊重しないことを考慮しても、やはりこのような相対パス指定は避けるようにするといいでしょう

# Do not write:
Get-Content .\README.md

# Especially do not write:
[System.IO.File]::ReadAllText(".\README.md")

# Instead write:
Get-Content (Join-Path $PSScriptRoot README.md)

# Or even use string concatenation:
[System.IO.File]::ReadAllText("$PSScriptRoot\README.md")

(Naming Conventions) Avoid the use of ~ to represent the home folder.

~ はプロバイダによって変わるので避けましょう
代わりに、${Env:UserProfile} や (Get-PSProvider FileSystem).Home が有用です

PS C:\Windows\system32> cd ~
PS C:\Users\Name> cd HKCU:\Software
PS HKCU:\Software> cd ~
cd : Home location for this provider is not set. To set the home location, call "(get-psprovider 'Registry').Home = 'path'".
At line:1 char:1
+ cd ~
+ ~~~~
    + CategoryInfo          : InvalidOperation: (:) [Set-Location], PSInvalidOperationException
    + FullyQualifiedErrorId : InvalidOperation,Microsoft.PowerShell.Commands.SetLocationCommand

余談 : PowerShell のインデントスタイル

そもそもこれを書きたかったのです。

PowerShell は、式モード(Script の解釈) の文法解釈においては Allman でも K&R 1TBS Style でも Stroupstrup もいけます。しかし、特に「PowerShell.exe のコマンドモード」と「PowerShell ISEなどの式モード」での構文解釈にずれがあるので、両方で不都合なくと思ったら K&R 1TBS Style が自然です。私自身 C# と一緒に書くことが多かったので Allman で書いていましたが PowerShellでも動くようにフォーマットのために ` 制御文字で調整はナンセンスかな、と思います。

同様に Stroustrup もないと思います。

K&R 1TBS Style

PowerShell の文解釈と式解釈にずれが生じません。

if ($this -gt $that) {
    Do-Something -with $that
} else {
    # NANIKA
}

BSD Allman

式解釈では問題ありません。が、PowerShell にはったときに、if の下の { や else でエラーがでます。

if ($this -gt $that)
{
    Do-Something -with $that
}
else
{
    # NANIKA
}

Stroupstrup

式解釈では問題ありません。が、PowerShell にはったときに、else でエラーがでます。

if ($this -gt $that) {
    Do-Something -with $that
} 
else {
    # NANIKA
}

ただし、これは、普段どちらで書いているかなどに左右されますし、チームでの共通化がとれていればいいのでしょう。

ちなみに、コミュニティでは、Stroupstrup が意外と多い結果です。

Where to put braces · Issue #24 · PoshCode/PowerShellPracticeAndStyle · GitHub

余談 : ドキュメントフォーマッター

いまやデファクトスタンダードとなった、VSCode でもフォーマット可能です。

marketplace.visualstudio.com

このあたりのエディタに任せる、という判断が私は好ましいと思っています。コードフォーマットより、内容に注力したいですからねぇ。

まとめ

以上がPowerShell Coding Style です。コーディングスタイルは、あくまでもその言語らしさを第一に、どうやれば言語の良さを活用できるかを念頭に考えられています。

特に PowerShell コミュニティは、強制を避けつつアドバイスとしてというスタイルで醸成を図っています。みなさんのコード公開時に悩むということが減ることを祈ります。

軽くまとめます。

C# で書く Cmdlet の Coding Style

ほぼ、C# のコーディング規則通りです。フィールドにprefix当りが違う、PowerShell Cmdlet として属性をどうすればいいのか、override 時にどうするのかがメインメインになります。あとは、Path などの利用しやすさ、ですね。最も重要なのは、Verb-Noun 形式での公開でしょう。

(Required) PSCmdlet を継承しましょう
(Required) Cmdlet は Atrribute で挙動や命名を表現できます
BeginProcessing/ProcessRecord/EndProcessing を用いて、入力を操作します
1. (Required) Pipeline で用いないなら BeginProcessing のみで表現します
2. (Required) Pipelin で用いるなら、ProcessRecord で入力を操作します
  1. (Strong) この時、入力ストリームはためずに即座に出力する方がいいでしょう
(Required) 出力型は OutputType 属性で明示しましょう
(Required) 出力オブジェクトは、内部で保持しないように
(Required) 例外は ErrorRecord を用いて適切に扱いましょう
(Required) Cmdlet は Module として配布しましょう
(Strong) パスを用いるCmdlet の Parameter には、Path や LiteralPath を容易するといいでしょう
1. (Strong) Path = Wildcard 入力を受け入れる場合に使います。PSPath を Alias として公開します
2. (Strong) LiteralPath = Wildcard 入力を受け入れない場合に使います
(Strong) 可能であれば Wildcard 入力を受け入れましょう
(Strong) 自前の型を用意した場合、custom Types.ps1xml を <YourProductName>.Format.ps1xm として用意するといいでしょう
1. (Strong) <YourProductName>.Format.ps1xm で、出力された表示を適切にしましょう
(Strong) 比較が必要ならIComparable を実装しましょう
(Strong) パイプラインで動くようにしましょう
1. (Strong) パイプラインの入力を受け入れるようにしましょう
  1. (Strong) その場合 ProcessRecord でハンドルします
2. (Strong) パイプラインではシングルレコードを返します
(Strong) Cmdletはケースインセンシティブにしましょう
(Advice) 名前空間に、.Command をつけましょう
(Advice) Cmdlet のクラス名は <Verb><Noun><Command> とします
(Advice) StopProcessing をオーバーライドして操作を止めましょう
(Advice) リソースを使う場合は、IDisposableを実装して明示的に呼び出します
(Advice) リモート動作させるなら、シリアライズしやすいといいですね

※ Design Guide に含めれていてここにないのですが、PascalCase などのルールは、C# のコード基準に準しています。が、prefix を推奨したりしていて必ずしも準していません。

PowerShell で書く Funcion の Coding Style

インテンドスタイルを除き、多くは .NET で Cmdletを書いたらどうするのか、を基本コンセプトにしています。ただ、PowerShell の言語仕様として、; を省略できるといった部分はいらないなら書かなくてもいい。Backticks 避けようね、といったどうすれば読みやすいか、言語として書きやすいかを大事にしています。

こちらも最も重要なのは、Verb-Noun 形式での公開でしょう。

AdvancedFunction が標準になっています。ぜひ検討してください
- [CmdletBindings] 属性がないと各種属性が書けないので当然かなと
特に [OutputType] は、PowerShell のオブジェクト = 型を伝える、パイプラインの伝搬という性質に強く影響があるため必須です
- ただし、OutputType と実際の返戻値は一致しなくても警告もエラーもでないので注意がいります。(ここがあまい)
#Requires タグは有益です。今後 Core が広まるなかで、より有益になるでしょう
- ただ、実行時にしかわからないあたりが触り心地はよくないです
Set-StrictMode -Version Latest は、あって困ることはないのでいれましょう
Verb-Noun 形式大事
- しかし、外部に露出しない関数は、わたしは VerbNoun と普通のメソッド形式で書いています。実は。そこ Verb-Noun にしなくてもいいと思っています。(この例は PowerShell Team のコードにも良く見ますね)
ローカル変数はcamelCase、パラメータなどは PascalCase、これ広まってほしいですね
Splatting は結構目にします。やりすぎると読みにくくなりますが、多くの面で有益でしょう
命名規則、省略を避けるという例は、PowerShell の目指す「わかりやすさ」に沿っており大事にしたいところです
Pipeline での動作がいらない時はbeing のみ書く
- 省略したときの挙動との一致ですね
Pipeline での動作がいる場合は、process で返却する
- end で返すことも多いのでふむですね
return はなるべく使わない
- これはreturn をすると制御、関数が終わることを意図しています
- が、ユーティリティ関数なら return を私は好んでいます

※ ここにはありませんでしたが、ASCII キーボードにおいて ' は " よりも Shift 入力が不要でタイポしにくいことから、文字列は ' が推奨されています。日本語キーボード? どっちでもいいですよねぇ。

*1:英語 : https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions

*2:英語 : https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines

*3:これは語弊があり、実際は .NET Framework の言語であれば F# で書くこともできます。が、ここでは話をシンプルにするためにこの前提でいきます。

*4:議論 : https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/24

*5:議論 : https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/24

目次