コメント 普通のコメントとTODOコメントとXMLドキュメントコメントと

TIPS

コメント

ソースコードには、これを読み書きするためのプログラマ用に、コンピュータ(コンパイラ)に解釈されない文字を書き込むことができます。これをコメントと言います。

論理構成が整然としており、メソッドや変数など適切に命名されておればコメントなんぞ不要であるという考えもあれば、

コードに表出されない情報や複雑な処理の概要などを一瞥で理解しやすいよう適切なコメントは多いほど良いという考えもあります。

ここでは、コメントとして何を書くべきかではなく、C#言語のソースコードでのコメントの記述方法について説明します。

普通のコメント

// 一行コメント

/* ~複数行コメント~ */
// 一行コメント
 
/*
 * 複数行コメント
 */
VisualStudio上ではコメントにしたり外したりするための編集用ボタンがあります。

TODOコメント

// TODO ・・・

コメントの最初にTODOを付与しておくと、タスク一覧という画面で確認することができます。

一覧はメニューの「表示」「タスク一覧」を選択すると表示されます。 以下のように一覧表示され、それをつつくとソースコードの該当行まで飛びます。 このような文字はトークンと呼ばれ、TODO以外にもHACKUNDONEなどがあります。

オプションで追加削除などのカスタマイズが可能です。

XMLドキュメントコメント

クラスやメソッドなどの説明を以下の形式でソースコードに記述したものをXMLドキュメントコメントといいます。

/// <タグ>~~

/// <summary>サンプルクラス</summary>
/// <remarks>XMLコメント説明用</remarks>
public class SampleClass
{
    /// <summary>
    /// コンストラクタ
    /// </summary>
    /// <remarks>
    /// インスタンスを初期化します。
    /// </remarks>
    public SampleClass()
    {
    }
}

XMLドキュメントとして推奨されるタグ

重要なのは概要を表すsummaryタグです。

他にもいくつかありますので、下記ページを参照下さい。

クラスとそのメンバー用として推奨される XML ドキュメント タグ - C#
この記事では、XML ドキュメント用の推奨タグの構文と定義について説明します。

XMLドキュメントの出力設定

プロジェクトの設定でビルドタブにあるXMLドキュメントファイルにチェックをすると出力フォルダにXMLファイルが出力されるようになります。

このファイルには付与してきたXAMLコメントがXML形式でまとめられています。

実行モジュールと共にこのファイルを配布するとライブラリを使用する側でインテリセンスが効くようになります。

(summaryタグの内容がツールチップ表示されるようになります。)

API仕様書の作成

また、この出力されたXMLファイルに対してツールを使用することによりAPI仕様書(DOCファイル)を生成することが可能です。
たとえば以下のようなツールがあります。
Quick Start | docfx
GitHub - EWSoftware/SHFB: Sandcastle Help File Builder (SHFB). A standalone GUI, Visual Studio integration package, and MSBuild tasks providing full configuration and extensibility for building help files with the Sandcastle tools.
Sandcastle Help File Builder (SHFB). A standalone GUI, Visual Studio integration package, and MSBuild tasks providing fu...
Doxygen: Doxygen
Source code documentation and analysis tool
TIPS
スポンサーリンク