id:satoshis:20041006#p1 より
プログラマの意図をコードに反映させることが重要なんだけど、それは裏を返せば、コードに反映されているプログラマの意図を読み取らせ伝えることが、その目的だ。メソッド名や引数・戻り値の説明だけでは表現しきれない意図を(単なるコメントではなく) Javadoc に書いておくと、コードを読まなくてもコードの意図を伝えられるメリットもある。
なるほど。目的は何かというと意図を伝えることであって、その方法としてコードを読んでもらうという方法と、ドキュメントに書くという方法があるということですね。
id:swat:20041006#1097025033 より
ドキュメントが役に立つかどうかは、そのドキュメントが正確であるかどうか、緻密であるかどうかには関係ない、ということ。
役に立つかどうかは、再利用するときに必要な情報が書かれているか否かで決まると思っている。
なるほど。正確である/ない × 再利用するときに必要な情報が書かれている/いないの2×2になるということでしょうか。
ドキュメントを書くときに、なにをに書こうかなあと考えます。Howは書く量が多くなってしまうでしょうし、コードを見る方がより確実でしょう。なるべく書かずに済ませたいです。Whatを伝えるには良い名前が必要で、意図を伝える名前が無いときにはドキュメントが必要。Whyは...ドキュメントが必要でしょうね。コードから「なぜ」このような設計なのかを汲み取るのはなかなか難しいのではないかと思います。ただ、きれいなソースを読むとなぜそうしたのかという意図が伝わってくることがあります。そのようなWhyやWhatが伝わるコードをいつでも書けるようになりたいと思っています。個人的には『XP導入編(ASIN:4894714914)』に書かれているように、意図を伝えるテストとコードを書くように心がけています。またJavadocを書くときには、なるべく事前条件と事後条件を書くように意識しています。
『リファクタリング(ASIN:4894712288)』の中では不吉な匂いとして「コメント」も挙げられています。曰く分かりにくいコードを補うためのコメントはbad smellであると。コメントを分かりにくいコードの免罪符にするのは避けたいと考えています。
考えをまとめます
- 意図は出来るだけ名前で示したい → 名前重要。
- ソースだけでは伝わらないものがある。伝えたいものがあるからドキュメントを書く
