ソースコードを見てて最近気になったこと。
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;
}