VisualStudio でコードを書いていて、summary テキストを入力する際、 基本的なコンストラクタやイベントハンドラに入力するテキストに困ったことはありませんか。 一部だけ書かないのも気持ちが悪いですし、統一されないのも気持ち悪いですし。 ここではいくつかの summary テキストについて、 msdn ではどのように書かれているかをまとめておきます。

基本的な書き方

まずは基本的な書き方についてまとめておきます。

1. 説明するテキストは「ですます」で書かれている。句読点などは付ける。
2. 引数などは体言止めで書かれている。ただし製目地するテキストが含まれる場合には「ですます」を含む。
3. 半角英数文字と全角文字の間には半角スペースが含まれている。

コンストラクタ

特別な処理を実行しないコンストラクタに付ける summary テキストって困りませんか。 msdn に従うと「○○クラスの新しいインスタンスを初期化します。」ですね。 あるいは省略して「新しいインスタンスを初期化します。」でも良いかもしれません。

イベントハンドラの引数 "sender" と "e"

MSDN の公式のサンプルを読んでいると凡そ次のように書かれていますね。 ただバージョンや実装先によって表記がまちまちで統一するのは難しい気がします。 結構実装先に応じた説明が書かれているんですよね。

一番短くてシンプルなのは「イベントのソース。/イベントのデータ。」です。 書くテキストに迷ってしまったらこれで統一してしまうのが無難な気がします。 長いとミスが出ますしね。

日本語版の sender の summary テキスト

イベントのソース。

イベントを発生させたオブジェクト。

日本語版の e の summary テキスト

イベントのデータ。

イベントの引数 / イベント引数(どっちが正しい翻訳か不明)

イベントデータを格納している "クラス名"。

イベントデータを含まないオブジェクト。(EventHandler Delegate など)

英語版の sender の summary テキスト

The source of the event.

The object that raised the event.

英語版の e の summary テキスト

Event arguments.

The クラス名 that contains the event data.

An object that contains no event data.(EventHandler Delegate など)