まずはじめに、API ドキュメントがいつ作られ、それがどのようにしてメンテナンスされ、いつその役割を終えるのか、といった観点で API ドキュメントのあるべき姿を考えてみましょう。
ドキュメントが追い討ちをかけるデスマーチ
システム開発の現場では、時としてドキュメント作成作業を先送りにしようとする強い圧力が働くことがあります。主な原因は開発スケジュールの遅延によるものでしょう。そんなときの彼らの言い分は大抵こうです。「どんなにドキュメントを書いても、それは動かない。とにかく今は動くものを作って納めることが最優先なのだ。」残念ながらその言い分は間違いではありません。
プロジェクトも終盤に差し掛かりいよいよ納期遅延が現実味を帯びてくると、焦ったマネージャーは新しい開発者をプロジェクトのメンバーとして迎え入れ、「これだけ開発者を揃えたのだから納期遅延は回避できるだろう」と胸をなでおろします。が、それと時を同じくして新しくプロジェクトに迎え入れられたメンバーはこう思うのです。「ドキュメントがないから、どこに何が書かれているのか、自分がどこに何を書けばよいのか、さっぱり分からない…。」
このような状況は、新参のメンバーの技術的スキルが高くても発生しうるものです。どんな技術者でもおそらく「ソース コードを追いかけるだけに終始してしまった」という時間が発生することは想像に難くないと思います。もちろん、新参のメンバーの技術的スキルが高ければ、ドキュメントが全くない状況から古参のメンバーと同じ程度の生産性が出せるようになるまでに要する時間 (習熟時間) は短くて済むかもしれません。開発者の技術的スキルが低ければ低いほど、また、システムの規模が大きければ大きいほど、さらに、システムの構造が複雑であれば複雑であるほど、このような無駄な(新参のメンバーにとっては苦痛でさえある) 習熟時間が長くなる傾向にあります。
API ドキュメントは、このような状況に対する決定的な打開策にはなりませんが、少なくとも習熟時間を短縮させる効果を見込めるのではないでしょうか。つまり、API ドキュメントの作成作業を先送りにせずにきちんと行っていれば、納期遅延の危険信号はもっと早いタイミングで点灯したかもしれませんが、API ドキュメントのおかげで新参のメンバーの習熟時間が短縮され、結果的にソース コードと API ドキュメントの双方を納期までに揃えることにつながったかもしれません。
今となっては誰も何もわからないシステムのメンテナンス
あえて説明するまでもないでしょう。ある日突然ソース コードだけ渡されて「改修してほしい」と言われたところで、開発者はしばらく目を白黒させたままになることは目に見えています。
この場合も API ドキュメントが決定的な打開策になるわけではありませんが、開発者がソース コードを理解するのに一役買うのは明らかです。他人が作ったプログラムの見たこともないソース コードという世界に旅立とうとする開発者にとって、たかだか API ドキュメントというガイド ブックであっても、全く持たないよりかは心強いというものです。
まとめ
API ドキュメントのライフ サイクルはソース コードのライフ サイクルと同一だと考えましょう。
- API ドキュメントはソース コードが作られるのと同時に作られるべきである。
- API ドキュメントはソース コードが共有されるのと同時に共有されるべきである。
- API ドキュメントはソース コードが変更されるのと同時に変更されるべきである。
- API ドキュメントはソース コードがレビューされるのと同時にレビューされるべきである。
- API ドキュメントはソース コードが廃棄されるのと同時に廃棄されるべきである。
実にシンプルなルールですが、API ドキュメントがプロジェクトにどう役立つかという点をマネージャーが理解していないと、いとも簡単に破られてしまうルールでもあります。
| API ドキュメントとは |
|
