ソースコードを見てて最近気になったこと。
コメント以下の部分の説明をしていて、丁寧!ってことなんだと思いますが、あまりいけてないと思います。
いけてないポイントたち
1)コメントの対象がどこまでなのかはっきりしない。
2)コードが正しいかどうか検証しにくい
3)一行コメント書くくらいなら、名前をつければいい
なので、 こういうなんか以下は〜です系のコメントは、
こうすれば、
1) どこまでが計算なのかがはっきりする
2) メソッド化したので、ユニットテストできる
3) 結局コメントと同じ効果が得られる
じゃあどういうコメントが良いのか。
いろいろな意見はあると思いますが、何しているのかではなく、なぜこう書かれているのかを説明するコメント。
さっきの例ではこんな感じ。
public void someCalculation(long number1, long number2) { ... // 最大公約数を計算する long a = number1; long b = number2; while (b != 0) { a = b; b = a % b; } long gcd = a; ... }みたいなコメント。
コメント以下の部分の説明をしていて、丁寧!ってことなんだと思いますが、あまりいけてないと思います。
いけてないポイントたち
1)コメントの対象がどこまでなのかはっきりしない。
2)コードが正しいかどうか検証しにくい
3)一行コメント書くくらいなら、名前をつければいい
なので、 こういうなんか以下は〜です系のコメントは、
public void someCalculation(long number1, long number2) { ... long gcd = computeGreatestCommonDivisor(number1, number2); ... } public long computeGreatestCommonDivisor(long a, long b) { while (b != 0) { a = b; b = a % b; } return a; }みたいにしたほうが良いと思う 。
こうすれば、
1) どこまでが計算なのかがはっきりする
2) メソッド化したので、ユニットテストできる
3) 結局コメントと同じ効果が得られる
じゃあどういうコメントが良いのか。
いろいろな意見はあると思いますが、何しているのかではなく、なぜこう書かれているのかを説明するコメント。
さっきの例ではこんな感じ。
public void someCalculation(long number1, long number2) { ... long gcd = computeGreatestCommonDivisor(number1, number2); ... } public long computeGreatestCommonDivisor(long a, long b) { // ユークリッド互除法を使って計算を高速化 while (b != 0) { a = b; b = a % b; } return a; }