diff --git a/csharp/index.md b/csharp/index.md index 6ac3906..f33e868 100644 --- a/csharp/index.md +++ b/csharp/index.md @@ -25,4 +25,5 @@ MSDN のガイドラインはライブラリの Public な範囲を対象とし - [命名規則](./naming-rules.md) - [コーディングスタイル](./coding-styles.md) - [イディオム](./idioms.md) +- [XML コメント](./xml-comments.md) - [付録](./appendix.md) diff --git a/csharp/xml-comments.md b/csharp/xml-comments.md new file mode 100644 index 0000000..dec27a4 --- /dev/null +++ b/csharp/xml-comments.md @@ -0,0 +1,123 @@ +## XML コメント + +.NET ではクラスやメンバーなどに XML コメントを記述することで、下記のような効果が期待できます。 + +- IntelliSense による開発の効率化 +- ドキュメントの自動生成 + +プロダクトコードの公開メンバーについては **必ず** XML コメントを記述します。 + +## コメント記述の例 + +### クラス + +#### ViewModel + +```cs +/// +/// に対する ViewModel です。 +/// +``` + +Base クラスなどで、View のクラス名が直接存在しない場合は、 ` などの○○を表すビューに対する ViewModel です。` のような表現にします。 + +### プロパティ + +#### アクセスの種類による末尾表現 + +`set` が公開 (public, protected) されている通常のプロパティ、もしくは ReactiveProperty (`ReactiveProperty`, `ReactivePropertySlim`) の場合は、内容のあとに「を設定または取得します。」をつけます。 + +```cs +/// +/// ○○を設定または取得します。 +/// +``` + +`set` が非公開もしくは `get` のみの場合、あるいは `ReadOnlyReactiveProperty`, `ReadOnlyReactivePropertySlim` の場合は、内容のあとに「を取得します。」をつけます。 + +```cs +/// +/// ○○を取得します。 +/// +``` + +#### 型による表現 + +##### boolean + +boolean の場合は「かどうか」をつけます。 + +```cs +/// +/// ○○かどうかを設定または取得します。 +/// +``` +```cs +/// +/// ○○かどうかを取得します。 +/// +``` + + +### メソッド + +そのメソッドの **外的なふるまい** を端的な文章で表します。可能な限り引数がどのような役割を果たすかの説明を加えてください。 + +内部実装についての説明が必要な場合は `` に記述します。 + +```cs +/// +/// 指定したファイルから書籍の一覧を読み込み、指定した顧客が借りている書籍を取得します。 +/// +/// ファイル名 +/// 顧客の名前 +/// 書籍のリストを返す +/// ファイルが見つかりません。 +/// +/// このメソッドは内部的に○○を呼び出します。 +/// +public Task> GetCurrentlyRentedBooks(string fileName, string customerName) +{ + +} +``` + +### メソッドの引数(パラメーター) + +名詞、名詞句、または体言止めで記述します。 + +```cs +/// ファイル名 +/// 顧客の名前 +/// 処理をキャンセルするための +``` + +型名があるほうが理解しやすい場合は `` タグで参照します。 + +### メソッドの戻り値 + +名詞、名詞句、または体言止めで記述します。 + +#### 条件によって戻り値が異なる場合 + +```cs +/// ○○の場合は△△、それ以外は▲▲ +``` + +#### 非同期メソッド + +```cs +/// 👈 Task の場合 +/// ○○を返す 👈 Task の場合 +``` + +### メソッドの例外 + +そのメソッドが**例外をスローする場合は、 `` を記述**します。 + +メソッド内で、例外を返す可能性のあるメソッドを呼び出している場合は、可能な限りその例外情報も記述します。 + +```cs +/// ファイルが見つかりません。 +/// ○○に空文字を指定することはできません。 +```