ドキュメントとコメント

コードと矛盾したコメントは、コメントがないよりも悪いです。 コードが変更されたときは、常にコメントを最新の状態に保つことを優先してください！

コメントは英語で、完全な文章でなければなりません。

コメントは英語で、完全な文章でなければなりません。コメントが短い場合は、最後のピリオドを省略することができます。

# Do not write:
# Increment Margin by 2
$Margin = $Margin + 2
# Maybe write:
# The rendering box obscures a couple of pixels.
$Margin = $Margin + 2

コメントを付けすぎないようにしましょう。 コードが特にわかりにくい場合を除き、各行の前にコメントをつけるのはやめましょう–そうすると、コードが分断されて読みにくくなります。

ブロックコメントは通常、後続のコードの一部または全部に適用され、そのコードと同じレベルにインデントされます。 各行は#で始まり、1つのスペースが必要です。

ブロックが特に長い場合（ドキュメントのテキストの場合など）は、<# ... #> ブロックコメントの構文を使用することをお勧めしますが、コメント文字をそれぞれの行に配置し、コメントをインデントする必要があります。

# Requiring a space makes things legible and prevents confusion.
# Writing comments one-per line makes them stand out more in the console.
<#
 .SYNOPSIS
 Really long comment blocks are tedious to keep commented in single-line mode.
 .DESCRIPTION
 Particularly when the comment must be frequently edited,
 as with the help and documentation for a function or script.
#>

ステートメントと同じ行にコメントがあると気が散ってしまいますが、明白なことを述べていない場合や、特に説明が必要な短いコードの行がいくつかある場合には、コメントは有用です。

コメントはコードステートメントから少なくとも 2 つのスペースで区切られ、同じコードブロック内の他のインラインコメントと一緒に並ぶのが理想的です。

$Options = @{
 Margin = 2 # The rendering box obscures a couple of pixels.
 Padding = 2 # We need space between the border and the text.
 FontSize = 24 # Keep this above 16 so it's readable in presentations.
}

コメントベースのヘルプは簡単な言葉で書くべきです。

あなたは大学のテクニカル ライティングのクラスで論文を書いているわけではありません。 不必要に大きな言葉は避け、説明は短くしましょう。

もしあなたが外国語で書いているのであれば、よりシンプルな言葉、よりシンプルな文章構造の方が良いですし、ネイティブの読者にとっても意味のあるものになる可能性が高いです。

完全でありながら、簡潔であること

場所

ドキュメントが関数と一緒にあることを確実にするために、ドキュメントのコメントは、上ではなく、関数の中に置くべきです。

もちろん、コメントを別の場所に置くことが悪いというわけではありませんが、この方がやりやすく、更新を忘れにくくなります。

詳細を ノートに書く

ツールがどのように動作するかを詳しく説明したい場合は、Notes セクションを使用してください。

機能を説明する

すべてのスクリプト関数コマンドには、少なくともその機能を説明する短い文が必要です。 これが Synopsis です。

各パラメーターの説明

各パラメーターは説明する必要があります。 パラメータの変更にコメントを同期させやすくするために、パラメータの文書化コメントの好ましい位置は、各パラメータの直上にある param ブロック内です。

param (
 # Param1 help description
 
 $Param1,
 # Param2 help description
 
 $Param2
)

残りのドキュメント コメントと一緒に .PARAMETER ステートメントを記述することも可能ですが、経験上、ドキュメントを記述するコードの近くに配置した方が最新の状態に保たれる可能性が高くなります。

使用例を提供する

ヘルプでは、主要な使用例ごとに必ず使用例を提供する必要があります。 使用例」とは、スクリプトを実行するために Powershell に入力する例のことで、機能をテストしているときにコマンド ラインからカット アンド ペーストすることもできます。

function Test-Help {
 <#
 .SYNOPSIS
 An example function to display how help should be written.
 .EXAMPLE
 Get-Help -Name Test-Help
 This shows the help for the example function.
 #>
 
 param (
 # This parameter doesn't do anything.
 # Aliases: MP
 
 
 $MandatoryParameter
 )
 <# code here ... #>
}

DOC-01 コメントベースのヘルプを書く

スクリプトや関数には、常にコメントベースのヘルプを書くべきです。