エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方

エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方

　システム開発のプロジェクトでjavaで書くのであれば、クラスやメソッドのコメントはjavadocになるはずだ。そういう人達は、本書を読んで参考になるはず。

　Javadocに限らず、システム開発におけるドキュメンテーションというと、怠惰で冗長な作業にも、システムの品質を上げるものにもなりうる。品質を上げるという意味でJavadocを有効活用したい。
　
　私の場合、プログラムの振る舞いを理解する方法としては、以下の順番で自分は理解するように努めている。

開発で使っているフレームワーク→設定ファイルを含むソースコード→Javadocなどのコメント→仕様書

状況にもよるが、ドキュメントにあたるのは最後で、動いている現状のソースコードにまず当たるようにしている。

　
　これを読んで、フレームワークが制約する設定と規約から作成しないといけないクラス以外で、特殊な処理があるようなロジックなどについては、Javadocに本書で述べているドキュメンテーションとしての視点から、記述したいと思う。そうすることで、自分が書いたソースコードの可読性、引き継ぎなどの学習コストを下げるとともに、Javadocを仕様書として渡せるようにしたい。

　
　ちなみに、開発者であれば、プログラムを書く事だけが仕事ではないことが多いはず、アーキテクト、仕様、設計、PJの進行方法、体制、工数などあらゆることに対してレビューなどで意見を言うし、必要であればドキュメント作成も行い、MTGなどで発言して意見を言う。交渉もできないといけない。
　つまり、各自が得意分野などを活かしつつ、プロジェクトに対してあらゆる形で、コミットメントできるように努めることが求められるはず。
　そういう意味でも、システム開発でのソースコードのコメントや、ドキュメンテーションついてもっと考えていいように思う。しかし、ドキュメンテーションも時間があれば、短く簡潔に分かりやすく作ることができるけど、時間がない状態で作成すると、推敲する時間やレビューする時間もないために、だらだらと冗長なものになりがちになることはよくあること。