Visual Studio .NETによるチーム開発事始め

Visual C# .NETでAPIリファレンスを作る(前編)

一色 政彦
2003/06/07


 あなたのチームでは、クラスやメソッドの知識を共有できているだろうか。

 チーム開発では、プログラムのソース・ファイルを共有するのが一般的だ。その場合、どこに何のクラス、メソッド、プロパティがあるのかを、チーム内のメンバー全員が正確に把握できるようにして、知識を共有する必要がある。知識の共有が十分でないと、開発時にクラスやそのメンバの使用方法、機能を調べるなどの余分な「時間と労力のコスト」がかかってしまうからだ。また、余計な時間がかかるだけでなく、同じ機能を持つクラスやメソッドを複数作ったり、使い方を間違えたりといった「トラブルが発生する可能性」が高くなってしまう。

1.APIリファレンスのすすめ

 チームでクラスやメソッドの知識を共有するには、クラスやメソッドのリファレンス・マニュアル(以下、APIリファレンス)を作成することが欠かせない。APIリファレンスがあれば、チーム内の全員がクラスやメソッドの情報を簡単に参照できるので、「余計な時間と労力のコスト」や「トラブルが発生する可能性」の双方を低減させることができる。なお、本稿でいう「APIリファレンス」とは、クラスやそのメンバ(メソッドやフィールドなど)の定義仕様を記述したドキュメントのことである。すべての開発者が毎日使っているものだろう。Visual Studio .NET(以下、VS.NET)に付属するMSDNライブラリ(クラス・ライブラリ・ヘルプ)もその1つである。

 APIリファレンスなしでチーム開発を行うのはかなり非効率的だ。開発チームにAPIリファレンスがないのは、いってみれば技術書籍に目次と索引がないようなものである。他人の作った書籍の内容を丸暗記している人などいないだろうから、ページを1からめくって、必要な情報が書かれたページをを探さなければならなくなる。効率的な開発を行うには、APIリファレンスは不可欠である。

 しかし、「すべてのクラスやメソッドに対して、開発者がAPIリファレンスのドキュメントを作成するのは、効率が悪くコストも高い」と考える人もいるだろう。実際の開発現場では、このような理由でAPIリファレンスの作成が見送られることが多いのではないだろうか。VS.NETでは、このような問題を解決するためのものとして、APIリファレンスを自動生成する機能が提供されている。そこで本稿では、このVS.NETの機能を実際に使用して、APIリファレンスを自動生成してみる。VS.NETが生成するAPIリファレンスはHTMLドキュメントなので、Webページとして簡単にチーム内に公開し、情報を共有できる。

 周知のとおりVS.NETでは複数の言語を利用可能だが、今回はVisual C# .NET(以下C#)の利用を前提とする。Visual Basic .NET(以下VB.NET)などでも本稿で示している手順でAPIリファレンス自体は自動生成できるが、次回で解説する「ドキュメント・コメントのタグ」を使用できるのは、現時点でC#だけである(ただし将来的には、ほかの言語でもサポートされる可能性があると、Microsoftのドキュメントの中で述べられている)。なお、VS.NETの新バージョンであるVisual Studio .NET 2003でもこのAPIリファレンスに関する機能はほとんど変更されていないため、本稿で述べている内容はそのまま適用できる。

 本稿では、VS.NETとC#によるAPIリファレンスの具体的な作成法を紹介し、生成されるリファレンスの内容とその見方、関連知識などについて解説する。全体を2回に分け、前編ではVS.NETでAPIリファレンスを生成する方法を説明し、生成したAPIリファレンスの表示内容とその意味を紹介する。後編では、APIリファレンス生成の基準となる「ドキュメント・コメントのタグ」の内容と、ソース・コード中での使い方を説明する。そして最後にAPIリファレンスの応用方法と関連知識を解説していく。

 

 INDEX
  Visual Studio .NETによるチーム開発事始め
  Visual C# .NETでAPIリファレンスを作る(前編)
  1.APIリファレンスのすすめ
    2.APIリファレンスの作成方法
    3.APIリファレンスを表示する
    4.APIリファレンスの概要
    5.クラス・メンバの詳細情報を参照する
 
インデックス・ページヘ  「Visual Studio .NETによるチーム開発事始め」


Insider.NET フォーラム 新着記事
  • 第2回 簡潔なコーディングのために (2017/7/26)
     ラムダ式で記述できるメンバの増加、throw式、out変数、タプルなど、C# 7には以前よりもコードを簡潔に記述できるような機能が導入されている
  • 第1回 Visual Studio Codeデバッグの基礎知識 (2017/7/21)
     Node.jsプログラムをデバッグしながら、Visual Studio Codeに統合されているデバッグ機能の基本の「キ」をマスターしよう
  • 第1回 明瞭なコーディングのために (2017/7/19)
     C# 7で追加された新機能の中から、「数値リテラル構文の改善」と「ローカル関数」を紹介する。これらは分かりやすいコードを記述するのに使える
  • Presentation Translator (2017/7/18)
     Presentation TranslatorはPowerPoint用のアドイン。プレゼンテーション時の字幕の付加や、多言語での質疑応答、スライドの翻訳を行える
@ITメールマガジン 新着情報やスタッフのコラムがメールで届きます(無料)

注目のテーマ

Insider.NET 記事ランキング

本日 月間