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 ドキュメントを記述する能力は、きっと不可欠な能力として評価されるようになるでしょう。
0 件のコメント:
コメントを投稿