仕様は JavaDoc に書いてある(キリッ)。
現実：JavaDoc をまじめに書いている人は少ない。
テストケース書いてるからエラーが出たらおかしいって事でしょ？
現実：テストケースが無いなんて当たり前。
ソース読めば分かるでしょ。
現実：ゴリゴリ書かれてるから読み解くだけで心が折れる。
そこで提案。
(可能な限り) 一行一コメントで書く(キリッ)
そもそも、JavaDoc があろうが仕様書があろうが読みにくいソースは動きが怪しい事が多い。メソッド名と処理してる内容が違うなんて普通。変数名が何を指してるのか分からないのも普通。期待している動きをするように継ぎ足し継ぎ足しで実装しているから、全体で見ると流れが見えないので帳尻あわせの処理が散在する。
怪しいロジックにだいたい共通してるのが以下の二つ。
- メソッド名と変数名がやけに長い
- メソッド名と変数名が役割に合ってない
レビュー＆メンテする側としてはかなり厳しい。何がしたいのか意図が読めない事が多い。そこで
(可能な限り) 一行一コメントで書く(キリッ)
が有るとかなり嬉しいんだけど。コメント行なんて目立たない色にすればそれほどうざい分けじゃないしメリットの方が大きいと思うんだけど。
