PowerShell ドキュメントのスタイルガイド

2025-05-20

この記事では、PowerShell-Docs コンテンツに固有のスタイルガイダンスを提供します。概要に記載されている情報に基づいています。

コマンド構文要素の書式設定

次の規則を使用して、要素が文で使用される場合に PowerShell 言語の要素を書式設定します。

適切な Pascal の場合は、コマンドレットとパラメーターに必ずフルネームを使用してください
指定されたエイリアスを示す場合にのみ使用する
PowerShell のキーワードと演算子はすべて小文字にする必要があります
次の項目は 、太字 のテキストを使用して書式設定する必要があります。
- 型名
- クラス名
- プロパティ名
- パラメーター名
  - 既定では、ハイフンプレフィックスなしでパラメーターを使用します。
  - 構文を示す場合は、ハイフンでパラメーター名を使用します。パラメーターをバックティックでラップします。
  例えば次が挙げられます。
```
The parameter's name is **Name**, but it's typed as `-Name` when used on the command
line as a parameter.
```
次の項目は、バックティック (`) を使用して書式設定する必要があります。
- プロパティとパラメーターの値
- 角かっこで囲まれたスタイルを使用する型名 - 次に例を示します。 [System.Io.FileInfo]
- 名前による登場人物の参照。例: ワイルドカードとしてアスタリスク文字 (*) を使用します。
- 言語キーワードと演算子
- コマンドレット、関数、スクリプト名
- コマンドとパラメーターのエイリアス
- メソッド名 - 例: ToString() メソッドは、オブジェクトの文字列形式を返します。
- 変数
- ネイティブコマンド
- ファイルとディレクトリのパス
- インラインコマンド構文の例 - コードサンプルについては Markdown を参照してください
  
  この例では、バックティックの例をいくつか示します。
```
The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns
the output to the `$files` variable.

```powershell
  $files = Get-ChildItem C:\Windows
```
```
  この例では、コマンド構文をインラインで示します。
```
To start the spooler service on a remote computer named DC01, you type:
`sc.exe \\DC01 start spooler`.
```
  ファイル拡張子を含めると、PowerShell のコマンドの優先順位に従って正しいコマンドが実行されます。

コードサンプルのマークダウン

Markdown では、次の 2 つの異なるコードスタイルがサポートされています。

コードスパン (インライン) - 1 つのバックティック (`) 文字でマークされます。スタンドアロンブロックとしてではなく、段落内で使用されます。
コードブロック - 3 つのバックティック (```) 文字列で囲まれた複数行のブロック。コードブロックには、バックティックの後に言語ラベルを付けることもできます。言語ラベルを使用すると、コードブロックの内容の構文を強調表示できます。

すべてのコードブロックをコードフェンスに含める必要があります。コードブロックにはインデントを使用しないでください。 Markdown ではこのパターンを使用できますが、問題が発生する可能性があるため、避ける必要があります。

コードブロックは、トリプルバックティック (```) コードフェンスで囲まれた 1 行以上のコードです。コードフェンスマーカーは、コードサンプルの前後にそれぞれ別の行に置く必要があります。開始マーカーには、オプションの言語ラベルを付けることができます。言語ラベルを使用すると、レンダリングされた Web ページで構文を強調表示できます。

サポートされている言語タグの完全な一覧については、一元化された共同作成者ガイドの「フェンスされたコードブロック」を参照してください。

発行では、コードブロックの内容をクリップボードにコピーできる [ コピー ] ボタンも追加されます。これにより、コードをスクリプトに貼り付けてコードサンプルをテストできます。ただし、すべての例が記述どおりに実行されるとは限りません。一部のコードブロックは、PowerShell の概念の基本的な図です。

このドキュメントでは、次の 3 種類のコードブロックを使用します。

構文ブロック
例示の例
実行可能な例

構文コードブロック

構文コードブロックは、コマンドの構文構造を記述するために使用されます。コードフェンスで言語タグを使用しないでください。この例では、 Get-Command コマンドレットで使用できるすべてのパラメーターを示します。

```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
  [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
  [-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
  [-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```

この例では、一般化された用語で for ステートメントについて説明します。

```
for (<init>; <condition>; <repeat>)
{<statement list>}
```

例示の例

PowerShell の概念を説明するには、例示の例を使用します。可能な限り、例で PowerShell プロンプトを使用しないようにする必要があります。ただし、例示の例は、コピーして実行用に貼り付けるわけではありません。これらは最も一般的に、理解しやすい簡単な例に使用されます。 PowerShell プロンプトと出力例を含めることができます。

PowerShell 比較演算子を示す簡単な例を次に示します。この場合、リーダーがこの例をコピーして実行するつもりはありません。この例では、簡略化されたプロンプト文字列として PS> を使用していることに注意してください。

```powershell
PS> 2 -eq 2
True

PS> 2 -eq 3
False

PS> 1,2,3 -eq 2
2

PS> "abc" -eq "abc"
True

PS> "abc" -eq "abc", "def"
False

PS> "abc", "def" -eq "abc"
abc
```

実行可能な例

複雑な例、またはコピーして実行することを意図した例では、次のブロックスタイルのマークアップを使用する必要があります。

```powershell
<Your PowerShell code goes here>
```

PowerShell コマンドで表示される出力は、構文が強調表示されないように出力コードブロックで囲む必要があります。例えば次が挙げられます。

```powershell
Get-Command -Module Microsoft.PowerShell.Security
```

```Output
CommandType  Name                        Version    Source
-----------  ----                        -------    ------
Cmdlet       ConvertFrom-SecureString    3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       ConvertTo-SecureString      3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-CmsMessage              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Credential              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-PfxCertificate          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       New-FileCatalog             3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Protect-CmsMessage          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Test-FileCatalog            3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Unprotect-CmsMessage        3.0.0.0    Microsoft.PowerShell.Security
```

Output コードラベルは、構文強調表示システムでサポートされている公式言語ではありません。ただし、このラベルは、発行システムが Web ページのコードボックスフレームに出力ラベルを追加するため便利です。 [出力コード] ボックスには構文が強調表示されません。

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

コードサンプルで行の継続を回避する

PowerShell コード例では、行連結文字 (`) を使用しないでください。バックティック文字は見にくく、行の末尾に余分なスペースがある場合に問題を引き起こす可能性があります。

PowerShell スプラッティングを使用して、複数のパラメーターを持つコマンドレットの行の長さを短くします。
パイプ (|) 文字、波括弧 ({)、丸括弧 (()、角括弧 ([) などの後で、PowerShell の自然に改行できるポイントを活用します。

例で PowerShell プロンプトを使用しないようにする

プロンプト文字列の使用はお勧めしません。これは、コマンドラインの使用方法を示すシナリオに限定する必要があります。これらの例のほとんどは、プロンプト文字列を PS>する必要があります。このプロンプトは、OS 固有のインジケーターとは無関係です。

プロンプトは、プロンプトを変更するコマンド、または表示されるパスがシナリオにとって重要な場合を示すために、例で必要です。次の例は、レジストリプロバイダーの使用時にプロンプトがどのように変わるかを示しています。

PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir

    Hive: HKEY_CURRENT_USER\System

Name                   Property
----                   --------
CurrentControlSet
GameConfigStore        GameDVR_Enabled                       : 1
                       GameDVR_FSEBehaviorMode               : 2
                       Win32_AutoGameModeDefaultProfile      : {2, 0, 1, 0...}
                       Win32_GameModeRelatedProcesses        : {1, 0, 1, 0...}
                       GameDVR_HonorUserFSEBehaviorMode      : 0
                       GameDVR_DXGIHonorFSEWindowsCompatible : 0

例ではエイリアスを使用しない

エイリアスを具体的に文書化している場合を除き、すべてのコマンドレットとパラメーターの完全な名前を使用します。コマンドレット名とパラメーター名は、適切なパスカルケース名を使用する必要があります。

例でのパラメーターの使用

位置指定パラメーターは使用しないでください。混乱の可能性を減らすには、パラメーターが位置指定であっても、パラメーター名を例に含める必要があります。

フォーマットコマンドレットのリファレンス記事

コマンドレットのリファレンス記事には、特定の構造があります。 PlatyPS はこの構造を定義します。 PlatyPS は、Markdown で PowerShell モジュールのコマンドレットヘルプを生成します。 Markdown ファイルを編集すると、PlatyPS は、 Get-Help コマンドレットで使用される MAML ヘルプファイルを作成できます。

PlatyPS には、コマンドレット参照用の特定の構造を必要とするスキーマがあります。 PlatyPS スキーマドキュメントでは、この構造について説明します。スキーマ違反によりビルドエラーが発生します。ビルドエラーは、投稿を受け入れる前に修正する必要があります。

ATX ヘッダー構造を削除しないでください。 PlatyPS では、特定の順序で特定のヘッダーセットが必要です。
H2 INPUTS ヘッダーと OUTPUTS ヘッダーには H3 型が必要です。コマンドレットが入力を受け取らないか、値を返さない場合は、H3 に None 値を使用します。
インラインコードスパンは、任意の段落で使用できます。
フェンスされたコードブロックは 、EXAMPLES セクションでのみ使用できます。

PlatyPS スキーマでは、 EXAMPLES は H2 ヘッダーです。各例は H3 ヘッダーです。たとえば、スキーマでは、コードブロックを段落で区切ることはできません。スキーマでは、次の構造のみが許可されます。

### Example X - Title sentence

0 or more paragraphs
1 or more code blocks
0 or more paragraphs.

各例に番号を付け、簡単なタイトルを追加します。

例えば次が挙げられます。

### Example 1: Get cmdlets, functions, and aliases

This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.

```powershell
Get-Command
```

### Example 2: Get commands in the current session

```powershell
Get-Command -ListImported
```

About_ファイルの書式設定

About_* ファイルは Markdown で書き込まれますが、プレーンテキストファイルとして出荷されます。 Pandoc を使用して、Markdown をプレーンテキストに変換します。 About_* ファイルは、すべてのバージョンの PowerShell と発行ツールとの間で最適な互換性を確保するためにフォーマットされています。

基本的な書式設定のガイドライン:

段落行を 80 文字に制限する
コードブロックを 76 文字に制限する
ブロッククォートとアラートを 78 文字に制限する
これらの特殊なメタ文字 \、$、および <を使用する場合:
- ヘッダー内では、これらの文字は先頭の \ 文字を使用してエスケープするか、バックティック (`) を使用してコードスパンで囲む必要があります。
- 段落内では、これらの文字をコードスパンに配置する必要があります。例えば次が挙げられます。
```
### The purpose of the \$foo variable

The `$foo` variable is used to store ...
```
Markdown テーブル
- About_*記事の場合、テーブルは 76 文字以内に収まる必要があります
  - コンテンツが 76 文字以内に収まらない場合は、代わりに箇条書きを使用します
- 各行で | 文字の開始と終了を使用する

次のステップ

編集チェックリスト