継続的な開発環境構築に向けて（Javadocだけでは解決できないこと）

継続的な開発環境構築に向けて（Javadocだけでは解決できないこと）

システム開発は「作って終わり」ではありません。業務内容に合わせた仕様変更や、バグへの対応、機能改善など様々な変更が発生します。ということは、継続的にドキュメントを管理する観点が必要となります。

ソースコードの変更理由はどこに書くべきか

図2は、仕様書やソースコード、テストコード、ドキュメンテーションコメントの関連とソースコードの改変の様子をあらわしています。

図2：ソースコード改変時の模式図
（画像をクリックすると別ウィンドウに拡大図を表示します）

ソースコードから仕様書への矢印は、前回作成したJavadocの拡張や仕様書タグで実現しています。ソースコードとテストコードの対応付けは、今回のテストタグで実現できています。それ以外の関連は、Javadocの通常の機能で実現可能です。

変更のない状態であればこれで十分ですが、問題となるのは「変更がある場合にソースコードの変更理由を記述する場所」です。変更した理由をドキュメ ンテーションコメントに追加して管理することもできますが、陳腐化した情報が蓄積されることによってソースコードが長くなり、可読性が悪くなることからあ まりお勧めできる方法ではありません。

普通、ソースコードは「ソースコード管理システム（以下、SCM）」を使って変更を管理しているはずです。変更した理由は、SCMに変更内容をコミットするときに、コミットログとして記述するべきです。

タスク管理と連動させる

ソースコードの変更には、変更に至るまでの経緯や背景があるはずです。しかしこれらをコミットログの中に延々と記述するのは現実的ではありません。そこで登場するのが「タスク管理との連携」です。

変更理由は冒頭にあげたように様々なものがありますが、具体的には変更するためのタスクを定義して管理することになります。図3は、タスクとコミットログの連携をあらわしています。

図3：タスクとコミットログの連携
（画像をクリックすると別ウィンドウに拡大図を表示します）

コミットログにタスクを識別できるIDを記述すれば、変更に至った経緯や背景を履歴から辿ることができるようになります。これを実現するツールとして「Trac」があります。

Tracについては以下の連載を参照してください。

最後に

本連載ではJavadocを起点にして、システム開発に関わるドキュメントの相互関係を整理してきました。

Javadocをきっかけにしましたが、Javadocのはたす役割を理解すれば、開発手法や開発言語に囚われないドキュメンテーションの本質がみえてきます。

それは「どのドキュメントに何を書くべきなのか」ということです。

本連載では様々なドキュメントが登場してきました。ドキュメント同士は関連があり、それらを通して開発に携わる人たちが情報共有を行うわけです。どのドキュメントが何をあらわすべきなのかが理解できれば「何を書くべきなのか」が自ずと明らかになります。

読者の皆さんが、どこに何を書けばいいか迷ったとき、本連載が道しるべのような役割を担えば幸いです。