トップ > C# > 【C#】コメントフィールドの書き方　C#編

【C#】コメントフィールドの書き方　C#編

C# .Net VisualStudio

関数やクラスの説明をする際、コード要素の上にコメントを書いて説明を入れます。
その説明の事をドキュメンテーションコメント（またはドキュメントコメント）と言います。

ドキュメンテーションコメントは基本的に厳格なフォーマットがありません。
どのように書いてもエラーで止まることはありません。
しかし、言語によって推奨している書き方は存在します。

C#では、ドキュメンテーションコメント領域の事を、C#ではコメントフィールドと呼びます。
コメントフィールドの書き方については推奨される書き方があります。
今回はコメントの書き方について触れます。

公式

本記事は下記の記載に沿って解説します。
docs.microsoft.com

書き方

コメントフィールドは、XML形式で入力します。
コメントは先頭にスラッシュ３つ（///）を付けて、要素ごとに推奨されるタグを追加します。

public class TestClass
{
  /// <summary>
  /// サンプルコード
  /// </summary>
  /// <param name="hoge">第１引数</param>
  /// <param name="fuga">第２引数</param>
  /// <returns>関数の結果</returns>
  public static int Sample(int hoge, string fuga) {
    /// 省略
    return result;
  }
}

Visual Studioの場合のショートカット方法

私が開発に使用している環境はVisual Studio 2019です。

Visual Studioの場合は、既存の関数やクラスがあれば自動的にコメントフィールドのひな型を作ります。
ひな形の作成は下記の方法があります。

  • コード要素の前で「///」と入力
  • ヘッダーメニューの「編集」メニューから、 IntelliSense > コメントの挿入の順に選択
  • コード要素の前で右クリックメニューを開いて、スニペット > コメントの挿入の順に選択

docs.microsoft.com

尚、既にコメントがある場合は自動で挿入されません。
改めてコメントフィールドを生成したい場合は、消してから実行してください。

記載するタグについて

コメントフィールドで使用できるタグは色々用意されています。

docs.microsoft.com

色々ありますが、基本的な要素は下記の３つです。
上記で記載した、Visual Studioで出力されるコメントフィールドのひな形でも出力される要素です。

タグ名 概要 ドキュメントページ
summary コード要素の説明 <summary> (C# プログラミング ガイド)
param 引数の説明 <param> (C# プログラミング ガイド)
returns 戻り値の説明 <returns> (C# プログラミング ガイド)

©︎2017-2018 WebSandBag