VB.NET開発者の皆さんは、メソッドやクラスの説明のためのコメントを、どのように書いていますか。
Visual Studioには、XMLドキュメントコメントという機能があります。（Visual Studio 2013 以降）
XMLドキュメントは、IntelliSenceとも連携し、外部ツールでも活用できます。とても便利なので、ぜひ活用しましょう。
従来のやり方
皆さんも、こんなコードを見たことがあると思います。
' **************************
' 関数名: Func1
' 引数: index 引数の説明
' 返り値: 返り値の説明
' **************************
Public Function Func1(index As Integer) As String
End Function
VB6のコードで、よくありますね。悪夢ですね。。。
XMLドキュメントコメントの付け方
クラスやメソッドの前の行に ''' とタイプするだけです。（半角でシングルクォート'を3つ）
すると自動で、
''' <summary>
'''
''' </summary>
''' <param name="index"></param>
''' <returns></returns>
等が作られます。
ちなみに、C#の場合は///（半角でスラッシュ/を3つ）です。
/// <summary>
///
/// </summary>
/// <param name="index"></param>
/// <returns></returns>
XMLドキュメントコメントを使うべき3つの理由
従来のやり方ではなく、XMLドキュメントコメントを使うべき3つの理由を考えましょう。
理由1. Visual Studio 標準の方法である
標準化された、しかも簡単な方法があるのに、独自のやり方に固執するのは、コードの可読性・互換性・保守性の面で好ましくありません。
素直に、標準の方法を使いましょう。
理由2. IntelliSense に表示される
XMLドキュメントコメントの内容は、IntelliSenceに表示されます。
オブジェクトブラウザーにも表示されます。
理由3. 外部ツールでソースコードの仕様書を自動作成できる
XMLドキュメントコメントは、コンパイル時にXMLファイルに出力することができます。方法は後述します。
出力されたXMLドキュメントコメントは、Sandcastle、NDoc、Monodoc などの外部ツールを用いて、HTMLファイルやヘルプファイルに加工し、ソースコードの仕様書を作成することができます。。
XMLドキュメントコメントの例
XMLドキュメントコメントは、
- モジュール
- クラス
- メソッド（Sub・Function・Propertyプロシージャ）
- メンバ変数
- 列挙型（Enum）
- 構造体（Structure）
などに対して付けることができます。
例を見てみましょう。
モジュール
''' <summary>
''' モジュールの説明
''' </summary>
Module Module1
End Module
クラス
''' <summary>
''' クラスの説明
''' </summary>
Public Class Form1
End Class
Sub・Function・Propertyプロシージャ
''' <summary>
''' Functionプロシージャの説明
''' </summary>
''' <param name="index">引数の説明</param>
''' <returns>返り値の説明</returns>
Public Function Func1(index As Integer) As String
End Function
''' <summary>
''' Subプロシージャの説明
''' </summary>
''' <param name="index">引数の説明</param>
Public Sub Sub1(index As Integer)
End Sub
''' <summary>
''' Propertyプロシージャの説明
''' </summary>
''' <returns>返り値の説明</returns>
Public Property Prop1
Get
End Get
Set(value)
End Set
End Property
メンバ変数
''' <summary>
''' メンバ変数の説明
''' </summary>
Public Value As String = ""
列挙型（Enum）
''' <summary>
''' 列挙型の説明
''' </summary>
Public Enum e_Enum1
End Enum
構造体（Structure）
''' <summary>
''' 構造体の説明
''' </summary>
Structure Structure1
End Structure
コンパイル時にXMLファイルに出力するには
プロジェクトコンパイル時に、ドキュメントコメントをXMLファイルに自動的に出力することができます。
設定を有効にする方法は、以下のとおりです。
1. プロジェクトのプロパティを開く
プロジェクトのプロパティを開くには、以下の2つの方法があります。どちらでもOKです。
- メニュー「プロジェクト｣ →「（プロジェクト名）のプロパティ」
- ソリューションエクスプローラー → 「My Project」をダブルクリック
2. 「コンパイル」タブ → 「XML ドキュメント ファイルを生成する」をチェック
これで、コンパイル時に出力フォルダに XMLファイルが出力されます。ファイル名は (プロジェクト名).xml です。
まとめ
以上、VB.NET/C#開発者がXMLドキュメントコメントを使うべき3つの理由と、使い方でした。
せっかく Visual Studio標準の、こんな便利な機能がありますので、ぜひ活用しましょう。
