SHFB 1.9.5.0 がリリースされています

しばらく見ていなかったのですが、Sandcastle Help File Builder（SHFB）のバージョン 1.9.5.0 が 2012 年 10 月 13 日付でリリースされています。

ポータブル クラス ライブラリ（Portable Class Library）や Windows Store App の API ドキュメント生成にも対応しています。

SHFB は本来コンソール アプリケーションである Sandcastle 用の GUI 環境として出発しており、古くは Sandcastle と SHFB はそれぞれ別にダウンロードしてセットアップする必要がありましたが、現在は SHFB に Sandcastle が同梱されており、SHFB のセットアップ プロセスの中で Sandcastle をセットアップすることが可能になっており、ドキュメント生成環境の構築手順も相当に簡略化されました。

Visual Studio との統合も対応済みで、*.shfbproj ファイルを Visual Studio 上で一つのプロジェクトとして読み込み、ソリューションに追加することも可能になっています。これで、Visual Studio 上でソース コードのコンパイルとドキュメント用 XML ファイルの生成から ドキュメント ファイルの生成まで、一気にビルドすることも可能です。が、ドキュメント ファイルの生成には時間がかかり、プログラムのデバッグ時にドキュメント ファイルを生成してしまうと生産性が著しく低下しますので、ドキュメント ファイルの生成は必要に応じて実行できるよう、ビルド構成などを編集することをお勧めします。

ドキュメント生成ツールの標準として必携です。

API ドキュメントのライフ サイクル

まずはじめに、API ドキュメントがいつ作られ、それがどのようにしてメンテナンスされ、いつその役割を終えるのか、といった観点で API ドキュメントのあるべき姿を考えてみましょう。

ドキュメントが追い討ちをかけるデスマーチ

システム開発の現場では、時としてドキュメント作成作業を先送りにしようとする強い圧力が働くことがあります。主な原因は開発スケジュールの遅延によるものでしょう。そんなときの彼らの言い分は大抵こうです。「どんなにドキュメントを書いても、それは動かない。とにかく今は動くものを作って納めることが最優先なのだ。」残念ながらその言い分は間違いではありません。

プロジェクトも終盤に差し掛かりいよいよ納期遅延が現実味を帯びてくると、焦ったマネージャーは新しい開発者をプロジェクトのメンバーとして迎え入れ、「これだけ開発者を揃えたのだから納期遅延は回避できるだろう」と胸をなでおろします。が、それと時を同じくして新しくプロジェクトに迎え入れられたメンバーはこう思うのです。「ドキュメントがないから、どこに何が書かれているのか、自分がどこに何を書けばよいのか、さっぱり分からない…。」

このような状況は、新参のメンバーの技術的スキルが高くても発生しうるものです。どんな技術者でもおそらく「ソース コードを追いかけるだけに終始してしまった」という時間が発生することは想像に難くないと思います。もちろん、新参のメンバーの技術的スキルが高ければ、ドキュメントが全くない状況から古参のメンバーと同じ程度の生産性が出せるようになるまでに要する時間 (習熟時間) は短くて済むかもしれません。開発者の技術的スキルが低ければ低いほど、また、システムの規模が大きければ大きいほど、さらに、システムの構造が複雑であれば複雑であるほど、このような無駄な(新参のメンバーにとっては苦痛でさえある) 習熟時間が長くなる傾向にあります。

API ドキュメントは、このような状況に対する決定的な打開策にはなりませんが、少なくとも習熟時間を短縮させる効果を見込めるのではないでしょうか。つまり、API ドキュメントの作成作業を先送りにせずにきちんと行っていれば、納期遅延の危険信号はもっと早いタイミングで点灯したかもしれませんが、API ドキュメントのおかげで新参のメンバーの習熟時間が短縮され、結果的にソース コードと API ドキュメントの双方を納期までに揃えることにつながったかもしれません。

今となっては誰も何もわからないシステムのメンテナンス

あえて説明するまでもないでしょう。ある日突然ソース コードだけ渡されて「改修してほしい」と言われたところで、開発者はしばらく目を白黒させたままになることは目に見えています。

この場合も API ドキュメントが決定的な打開策になるわけではありませんが、開発者がソース コードを理解するのに一役買うのは明らかです。他人が作ったプログラムの見たこともないソース コードという世界に旅立とうとする開発者にとって、たかだか API ドキュメントというガイド ブックであっても、全く持たないよりかは心強いというものです。

まとめ

API ドキュメントのライフ サイクルはソース コードのライフ サイクルと同一だと考えましょう。

• API ドキュメントはソース コードが作られるのと同時に作られるべきである。
• API ドキュメントはソース コードが共有されるのと同時に共有されるべきである。
• API ドキュメントはソース コードが変更されるのと同時に変更されるべきである。
• API ドキュメントはソース コードがレビューされるのと同時にレビューされるべきである。
• API ドキュメントはソース コードが廃棄されるのと同時に廃棄されるべきである。

実にシンプルなルールですが、API ドキュメントがプロジェクトにどう役立つかという点をマネージャーが理解していないと、いとも簡単に破られてしまうルールでもあります。

---

API ドキュメントとは

高品質な API ドキュメントの作成方法

API ドキュメントとは

API ドキュメントとは、クラス ライブラリをはじめとするプログラムに含まれるクラスやメソッドといった構成要素がどのような機能を持ち、どのように利用されるべきかを詳細に説明する文書のことです。

.NET Framework クラス ライブラリの API ドキュメント

.NET Framework 向けの標準的なシステム開発では基盤となる .NET Framework クラス ライブラリについての知識が必要になりますが、.NET Framework クラス ライブラリがサポートする機能はバージョン アップを重ねるごとに増えており、すべてを把握することは非常に困難です。どのクラスがどのような機能を提供するものであるか、といった情報はプログラミング言語で記述されたソース コードからではなく自然言語で記述されたドキュメントから読み取るほうが容易に理解できることは想像に難くないでしょう。

.NET Framework クラス ライブラリでは、.NET Framework クラス ライブラリがサポートする機能、つまり .NET Framework クラス ライブラリの API を開発者が理解することを手助けするために、API ドキュメントが用意されています。この API ドキュメントは、.NET Framework 向けの標準的な統合開発環境である Microsoft Visual Studio でも有効に活用されています。例えば、編集中のソース コードの任意の場所で F1 キーを押下すると、クラスやメソッド等の API ドキュメントが表示される機能は、誰もが一度は利用した経験がある機能でしょう。そのほかにも、ソース コード編集中に現れる入力候補表示機能 (IntelliSence) でもメソッドや引数の概要が自然言語で表示されたり、特定のアセンブリ中で実装されているクラスやメソッド等をツリー表示できるオブジェクト ブラウザーでも、クラスやメソッド等の概要情報が自然言語で表示されたりする機能があります。これらの機能は .NET Framework クラス ライブラリの理解を手助けするだけではなく、開発作業そのものの効率化にも役立っています。

カスタム クラス ライブラリの API ドキュメント

実際のシステム開発では、そのシステムの基盤になったり機能の基本的な実装を提供したりする、カスタム クラス ライブラリを開発する場合があるでしょう。また、既存のカスタム クラス ライブラリを利用して新しいシステムを開発する場合もあるでしょう。中には独自のアプリケーション フレームワークをクラス ライブラリとしてメンテナンスしており、それを活用することで迅速なシステム開発をセールス ポイントとしている企業もあります。

このようなカスタム クラス ライブラリを利用したシステム開発を行う場合には、.NET Framework クラス ライブラリの API ドキュメントはもちろん、カスタム クラス ライブラリの API ドキュメントも用意されていれば、開発者はカスタム クラス ライブラリの API ドキュメントを参照しながら、効率的に開発作業を進めることが可能になるでしょう。逆に API ドキュメントのないカスタム クラス ライブラリを利用することは、開発者にとって大きな困難と苦痛を強いるものになるでしょう。

つまり、カスタム クラス ライブラリには API ドキュメントが欠かせない存在なのです。

アプリケーションの API ドキュメント

カスタム クラス ライブラリを用いない場合や、非常に規模が小さいアプリケーションであっても、API ドキュメントは有効です。

小規模なアプリケーションであっても、最近のシステム開発の現場では MVC 等の実装パターンを導入してアプリケーション内の各クラスの役割分担を明確にしている場合があります。このようなアプリケーションは、小さいながらも内部に独自のエコ システムを構築していることに他ならず、エコ システム内の各クラスがどのような機能を提供しているかといったような情報を API ドキュメントとして残しておくことはとても自然です。

さらに、システム規模の大小に関わらず、API ドキュメントは既存のソース コードの理解を促すという点で、システムのメンテナンス (改修、拡張等) 時に威力を発揮します。

システム開発時の開発メンバーがそのままシステムのメンテナンスに関わり続けるというのはシステムにとっては非常に幸運ですが、残念ながらシステムのリリースから時を経れば経るほど開発メンバーがメンテナンスに関わることが困難になってくるのが現実です。むしろ、開発メンバーが一人も居ない (連絡も取れない) 状態のシステムをメンテナンスしなければならない局面に出くわしたことがない開発者を探すほうが難しいかもしれません。

このような局面でも、メンテナンスを行う開発者にとって API ドキュメントはソース コードと合わせて貴重な情報源になります。

まとめ

規模の大小や、プロジェクトの種類 (クラス ライブラリ開発か、アプリケーション開発か) といったことは一切関係なく、何らかのソース コードを書いたならば、そのソース コードによって提供される機能や特徴といった情報を API ドキュメントの形で残しておくべきです。

そして、これからの開発者にとって、API ドキュメントを記述する能力は、きっと不可欠な能力として評価されるようになるでしょう。

---

高品質な API ドキュメントの作成方法

API ドキュメントのライフ サイクル

高品質な API ドキュメントの作成方法

Microsoft Visual Studio とオープン ソースのツール群を使用して、C# や Visual Basic をはじめとする .NET Framework 向けプロジェクトの高品質な API ドキュメントを作成する方法を解説します。

主に Microsoft Visual Studio 2010 上の C# プロジェクトを対象にしていますが、その他のバージョンの Microsoft Visual Studio についての情報や C# 以外の言語における情報も可能な限り掲載します。

• 概念編
  • API ドキュメントとは
  • API ドキュメントのライフ サイクル