PowerShell に慣れていない人がスクリプトを書き始めると、通常はコードに注目します。 結局のところ、コードは物事を実現するものだからです。 実行可能なコードはもちろん重要ですが、あまりにも多くのコードを書きすぎて、それが何をするものなのかを忘れてしまったらどうなるでしょうか。

もしあなたがチームに所属していたら、あなたが書いているコードを彼らは理解しているでしょうか？

スクリプトに説明的で有益な PowerShell コメントを書くことで、私たち人間がコードの意図や結果を理解するのに役立ちますし、おそらくかつて遭遇したエッジ ケースについても説明できます。

この記事では、PowerShell のさまざまな種類のコメント、どのコメントを使用するか、そしてスクリプトで効果的に使用する方法について学びます。

コードを書いて、数週間または数ヶ月後にレビューしなければならなかったことはありませんか？ おそらくですが。 そんなに後になってから理解できましたか？ そうではないかもしれません。 コードに有用なコメントを残していれば！

ほとんどのプログラミング言語には、コメントの概念があります。 PowerShellも例外ではありません。 PowerShellでは、あなたの友達は#です。

以下のコード例は、あるスクリプトからの抜粋ですが、何をするかは1行目のPowerShellスクリプトのコメントを参照してください。

# Get all files with TXT extension, show the name of each file and then delete them.Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName}

しかし、以下のような簡潔なコマンドに遭遇した場合はどうでしょうか？

"{0},{1}" -f (gm -input (1..20) -name count), (1..20).count

コメントを追加することで、あなたやあなたのコードを読む人に大きなメリットをもたらします。

#Check whether the object has a property named "count". Then, return true or false."{0},{1}" -f (gm -input (1..20) -name count), (1..20).count

前のセクションでは、コメントは # 文字で始まることを学びました。 複数行のコメントを作成することを止めることはできません。 実際、PowerShell 2.0以前では、複数行のコメントを作成するには、単一行のコメントを複数行作成するしかありませんでした。

コメントは簡潔にまとめるのが良いのですが、PowerShell のコメントブロックとも呼ばれる、PowerShell の複数行コメントを使用する必要があるシナリオもあります。

PowerShell のコメントブロックは、<##>で終わります。

長いコメントを複数行に分割する

スクリプトの中に長いコメントがあるのは避けられないことがあります。 このような長いコメントは、現在の表示の枠をはるかに超えてしまうことがあります。 そのような場合、コメント行全体を読むためには、水平方向にスクロールし続ける必要があります。

たとえば、次のような長い単一行のコメントではなく、

# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display. And when that happens, you will need to keep on scrolling horizontally to read the entire comment line.

次のような読みやすい複数行のコメントにしてみてはいかがでしょうか。

<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>

説明的なテキストの追加

スクリプトをダウンロードしたり書いたりしたときに、適当な名前や説明的でない名前で保存したことはありませんか?

スクリプトを開いてそれが何であるかを調べるとき、スクリプトが何のためにあるのか、誰が作成したのか、いつ作成されたのかなど、有用な詳細が内部に記載されているといいですね。

PowerShell のブロック コメントは、スクリプトに説明文を追加するのに便利です。

以下は、スクリプトが何であるか、いつ最終更新されたかを説明し、スクリプトを実行するときに何をしてはいけないかという警告を示すブロック コメントの例です。

<# Using this script will export the email addresses of all mailboxes in the Exchange organization.WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL.Last update: Feb 16, 2020#>

要件とステップの文書化

スクリプトに特定の実行方法がある場合や、実行するための特別な要件がある場合、ブロックコメントはスクリプトや関数の中でそれを文書化するのに役立ちます。

以下は、ブロックコメントを使用して要件とステップを文書化した例です。

<#This function requires an encrypted credential XML file that will be usedto authenticate with Office 365.If you don't have this yet, follow these steps.1. Open PowerShell2. Run this command - 'Get-Credential | Export-CliXml .\credential.XML'3. Make sure to save the XML file inside the same folder as the script.NOTE: The credential XML file will only work on the same computer and the same accountused to generate it.#>

既存のコードをコメントアウトする

コメントは、コメントを追加する目的だけではなく、使用されます。

たとえば、スクリプトをテストしたり、デバッグしたりすることがあると思います。

たとえば、Active Directory でユーザーのリストを取得し、そのリストを foreach ループで処理して、Set-AdUser コマンドレットを使用して各ユーザーの部署名を設定するスクリプトがあるとします。

<#This script will get all AD users matching the filterand each user's department name will be changed to 'Finance'.#>$adUsers = Get-ADUser -Filter *foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}

しかし、Set-AdUser 行を実行せずに foreach ループをテストしたい場合は、その特定の行を次のようにコメントアウトするだけです：

foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" #Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}

これで、各ユーザーの部署名を実際に変更することなく、スクリプトを安全にテストすることができます。

TIP: Visual Studio Code では、キーボード ショートカットの「CTRL + /」を押すことで、1 行または複数行をコメントアウトできます。

さて。 複数の行をコメントアウトしたい場合は、各行の先頭に #<# #> ブロックで複数の行を囲むかのどちらかを選択できます。

$adUsers = Get-ADUser -Filter *<# foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'} #>

TIP: Visual Studio Codeでは、1行または複数行のコードをハイライトして「ALT + SHIFT + A」のキーボードショートカットを押すことでも、コメントブロックを作成できます。

コメントベースのヘルプ

ベースのヘルプ

スクリプトや関数をよりプロフェッショナルに見せたいとき、コメントを追加することで、そのようにすることができます。 コメントベースのヘルプを追加することで、よりプロフェッショナルに見せることができます。

コメントベースヘルプのキーワードや構文については、「コメントベースヘルプについて」のページをご覧ください。

以下のサンプルコードでは、Get-WhatTimeIsItNow.ps1という名前のスクリプトにコメントベースのヘルプが含まれていることを示しています。

<#.SYNOPSISShort description of the script.DESCRIPTIONLong description of the script.EXAMPLEPS C:\> Get-WhatTimeIsItNow.ps1Explanation of what the example does.INPUTSInputs (if any).OUTPUTSOutput (if any).NOTESGeneral notes#>Get-Date -Format t

コメントベースにより、Get-HelpGet-Help <script/function>を実行すると、PowerShellは以下のように、スクリプトに含まれる「ヘルプ」テキストを返します。

TIP: Visual Studio Codeでは、エディタペインでcomment-helpと入力することで、デフォルトのコメントベースのヘルプブロックを挿入することができます。

ベストプラクティス

ここでは、効果的なコメントを作成するためのベストプラクティスと呼ばれるものをいくつか紹介します。

コードを書いているとき、コメントに行番号への参照を追加したいと思うかもしれません。 行番号の参照を追加することで、コードがより理解しやすくなると考えるのは正しいかもしれません。 ただし、そのコードが絶対に修正されないと確信している場合に限ります。

新しいコードの行がスクリプトに挿入されたとします。 そうすると、コメント内のすべての行番号参照がすでにシフトしていることになります。

私たち人間は、上から下に向かって読むことに慣れています。

私たち人間は、上から下へと読むことに慣れています。追加するコメントが後続のコード行にとって重要であれば、前にコメントを追加するのは論理的なことです。

結局のところ。

結局のところ、スクリプトにスクリプトについてのコメントを追加する場合、コメントはコードの後ではなく前に置く方が賢明ではないでしょうか。

前の例と同じで、コメントをコードの後に置くことは、たとえそれが同じ行にあったとしても、コードの下にコメントを置くのと同じことです。

コードの最後にコメントを追加すると、コードを修正することに集中する代わりに、コードの変更に伴ってコメントが移動することも気にしなければならないので、編集ミスの原因になります。

Do not state the obvious

時には、コードがあまりにも単純で、意図がすでに明白であるため、そこにコメントを追加することが無駄になってしまうことがあります。

コードが一目瞭然だと思う場合は、コメントの追加を省略することを検討するとよいでしょう。

PowerShell でコメントを適用する方法には厳格なルールはありませんが、コメントを使用する方法についてはテスト済みの実証済みの推奨事項があります。 最終的には、最初から最後まで重要なことを思い出させるために、スクリプトでコメントをどのように使用するかはあなた次第です。

Further Reading