コメント
ソースコードには、これを読み書きするためのプログラマ用に、コンピュータ(コンパイラ)に解釈されない文字を書き込むことができます。これをコメントと言います。論理構成が整然としており、メソッドや変数など適切に命名されておればコメントなんぞ不要であるという考えもあれば、
コードに表出されない情報や複雑な処理の概要などを一瞥で理解しやすいよう適切なコメントは多いほど良いという考えもあります。
ここでは、コメントとして何を書くべきかではなく、C#言語のソースコードでのコメントの記述方法について説明します。
普通のコメント
// 一行コメント/* ~複数行コメント~ */
// 一行コメント
/*
* 複数行コメント
*/
TODOコメント
// TODO ・・・コメントの最初にTODOを付与しておくと、タスク一覧という画面で確認することができます。
一覧はメニューの「表示」「タスク一覧」を選択すると表示されます。 以下のように一覧表示され、それをつつくとソースコードの該当行まで飛びます。 このような文字はトークンと呼ばれ、TODO以外にもHACKやUNDONEなどがあります。
オプションで追加削除などのカスタマイズが可能です。
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