プログラムコード上のコメント

出来るだけコメントを書かないようにしている。面倒だからではなくて、コメントで説明してしまうと判らないコードの免責になってしまうことが多いから。
例えばこういうことはやりたくない（勿論、極論だけれども）。

class Hoge {
private int count;
public boolean isOver() {
// 10を超える場合は大きすぎるので真を返す
return count > 10;
}
}

こういうのはコメントに書かずにコード上で表現した方が良いと思う。

class Hoge {
private static final int MAX_SIZE = 10;
private int count;
public boolean isOver() {
return count > MAX_SIZE;
}
}

ただし、逆にコメント（ドキュメント）が必要な場合もあると思う。それはコードを読まなくても解るようにするためのもの。例えば、APIのドキュメントとかは必要だと思う。
よくコメントにはコードの動作ではなく仕様を記載するべきだということが言われていると思う。それはそうだと思う。コードの動作は読めば解る訳で（たまに信じられないくらい難解な一行とかもあるけれど）。ただ、もう一歩言うのであれば、仕様がコードで表現できる場合はコメントではなくコードに反映させるべきだと思う。理由は簡単でコードは実際に利用されるけれども、コメントは書いた場所にしか存在しないから。