ドキュメントコメントについて

どうもJudaです。

ドキュメンテーションコメントの重要性について語ろうと思います。

コメントをつけるといっても、どれぐらいの詳細を書き込むのか、あるいはもっと根本的に、何を書くのか、ということは突き詰めると意外と決まっていないことが多い。もっともちゃんとした規約があるところもあるのでしょうが、それらを新規に制定していこうと思うと、Try&Errorではドキュメントを書く人、主に開発者が死にますのでここは重要ですよ。
その勉強のために、一冊本を調達しました。
エンジニアのためのJavadoc再入門講座
この本はまだ途中までしか読んでいないのですが、なかなかためになります。Javadocについて書かれていますが、ここからメタ＜ドキュメンテーションコメント付け＞を引き出していこうと思っています。

なにがドキュメンテーションコメントを深くつきつめる動機になったのか。

それは、レガシー化しているコードを保守、拡張、利用するということが通例であるのに、それらについての一家言をもっている人が周りにいなくて、個人的に困ったことになっているからです。またコメントと同時的にテストやテスト手法、ソフトウェアのもつ責任範囲など、主にソースコードを利用し、改変、配布する場合におこる問題への対処を根とした調査ですね。まわりもリファクタという行為に関してはまだ認知度が高いみたいだが、これに付随するテストに関してはあまり重要視していない。そしてリファクタを行う前にテストを用意しないと行けないという罠。どう考えても、テストは重要だなぁ。と、それを改変するときには、同時にドキュメントを正確にしていかないといけませんなぁという流れです。

そして、一番の関心事は、すべての問題の責任を押し付けられる可能性があることに対して、なるべく強固な方法で防御をしないと、何をされるかわからない危険です。危険は回避したいです。

ドキュメンテーションコメントは、それを利用する人に向けてという意味合いが強いので、ほとんどはPublic 向けな規則ですが、クラスの再利用の問題もあるので、個人的にはProtected、Virtualなメソッドに対しては原則的に必要ですし、例外を投げる可能性のある関数にも必要だと思います。さらに話を広げますと、例外の基準。こちらも実装をしている段階で、いろいろとも問題になります。通常の処理ではありえないものが例外ですが、実装段階でそれらをトラップできるとなると、それは例外なのか？という疑問もあります。そこのところも含めて、上記の書籍には幾分かの指針が書かれていたので、それをもとに考えを深めていく。