きっかけ
javadocをがっつり書くと、コメント行の比率が高くなってしまうので、目安を知るために、良くつかっているライブラリではどうなのかを、SonarQube 3.7.4で調べてみた。（手元にあるのが昔つくったやつなのでsonarのバージョンが古いです。）
数字を書き出すがめんどいので、画面スクショをはっていく。
Guava
Joda-Time
Commons-Collections
Commons-Email
Super CSV
jackson-core
ORM
使ったこともないのも含めて、ORマッパーも追加で調べてみた。
Ebean
MyBatis
Iciql
Doma
所感
公開APIへのjavadocコメントをつけている比率は、軒並み高いですね。
規模が小さいと100%ですし、guavaみたいにでかいやつでも90%を越えていたり。
コメント率もどれも20%は余裕で越えていた。ORMの調べてみたら、意外と低いのもあった。
javadocコメントの規約やプロジェクトの方針によるのだろうが、コメント率は結構幅がある。
結論?
設計書など、他のドキュメントがあるなら20%あたりでも良さそう。
ソースコードとjavadocだけでやっていくなら、30~40%までいっても問題なさそう。
公開APIにjavadocコメントを全てつけるかどうかはケースバイケースだろうか。