矢崎です。誤訳や言い回しの変なところがあれば、どんどん
ご指摘ください。
XPractices 6.
Method comments(メソッドにつけるコメント）
一般的に、私たちは書いたメソッドにコメントをつけない。Beckは、
コメントは、メソッドがまだ書き終わっていないことを示すのに使
われるのだと教える。これが、私たちがコメントを使うやり方である。
一見したところでは不明瞭なメソッドがあった場合、私たちはその
メソッドが明瞭になるように、名前を変えたり、リファクタリングを行
うことを試みる。明確にできなかった場合には、そのメソッドにコメ
ントをいれる。
メソッドが見慣れないアルゴリズムを含んでいたり、どこかで公表
されたアルゴリズムを含んでいたりして、それらについて参照した
い場合はコメントをいれるかもしれない。
メソッドがパフォーマンスの点からボトルネックであると見られてい
て、効率的になるように特殊な方法で書き直された場合、私たちは
それにコメントをいれるであろう。
おそらく、システムの１パーセントにも満たないメソッドしかコメント
を持たない。コメントが必要なメソッドにはコメントをいれる。私たち
のやり方で書かれたメソッドのほとんどは、コメントを必要としない。
反論
より明瞭になるよう、全てのコードはコメントを持つべきである。
・正しく書かれたSmalltalkのコードは、通常その意図を直接に表
す。だからコメントは必要ない。もしコメントが必要ならば、その
コードはもっとリファクタリングする必要があるのだ。
・もしあなたが、コメント付きのSmalltalkのコードを持っていて、そ
のコメントが必要だと考えているならば、それを私に送ってほし
い。私はそれがコメントが不要になるようリファクタリングできる
かどうか見てみる。コメントが不要になったかならなかったか、
いずれの場合でも、私は結果を私のWebのページにのせるつ
もりである。コードを送る場合には、ユニット・テストも必ずつけ
ておいてください。
---
オリジナル http://www.xprogramming.com/
Copyright (c) 1999, REJeffries et al. (ronjeffries@....org)
--
矢崎 博英 <firo@....jp>