読者です 読者をやめる 読者になる 読者になる

Fight the Future

何かを始めたら、半分成功したのと同じ

大事なことだから2回言うけど、ソースコードのコメントは書けばいいものじゃない

pg

僕は他人のソースコードを批評するほど、すごいプログラマでも何でもない、
ただの初級プログラマだけど、これだけは言える。


ソースコードに、こういうコメントは一切必要ない。絶対必要ない。

public void connectToAndQueryDatabase(String username, String password) {
  // コネクションを取得
  Connection con = DriverManager.getConnection
    ("jdbc:myDriver:myDatabase", username, password);
  
  // ステートメントを生成
  Statement stmt = con.createStatement();

  // select文
  String sql = "SELECT a, b, c FROM Table1";

  // select文を実行し、結果を取得
  ResultSet rs = stmt.executeQuery(sql);

  // 結果の件数分ループ
  while (rs.next()) {
    // カラムaの値を取得
    int x = rs.getInt("a");
    // カラムbの値を取得
    String s = rs.getString("b");
    // カラムcの値を取得
    float f = rs.getFloat("c");
  }

JavaとかJDBCとかDB接続とか、そういうコンテキストは一切関係なしに、
プログラミングにこういうコメントはいらないんだ。


(前にも似たようなことは書いてる。)
コメントには内容ではなく理由を書く - Fight the Future じゅくのblog
http://d.hatena.ne.jp/jyukutyo/20090325/1238047989


こういうコメントに、どんな意味がある?メリットがある?
「コメントは書こう」みたいな、曖昧な意見に盲目的に従っているにすぎない。


このコメントの何がいけないのか?
それは、「コードがしていることを、自然言語で記述したにすぎない」コメントだからだ。


コードがしていることは、コードを読めばわかる。
同じことが2回書いてあるなんて、ただのノイズでしかない。
読みにくくなるだけなんだよっ!コードが!


そして、こうしたコメントは、変更が入るたびに不正確になっていく。
コメントは、コードを読んでもわからないことを書く。
書く必要があるコメントだけ、書く。


コメントは、なぜそういうコードを書いたのかを書くんだ。
何をしているコードかを書くんじゃないんだ。


偉大なプログラマの引用も事欠かないくらいの、当たり前のことである。

コメントはコードの意図を説明するべきものであり、
コード自体を説明するべきものではないのです。
コードの内容を言い換えても何の役にも立ちません。
そしてそれが不正確だった場合、コメントは誤解を招くもの以外の何者でもなくなります。
コメントはそのコードが存在する理由、その意図、その意図を達成する上で用いている小細工を説明するべきなのです。

言語設計者たちが考えること p.83 Charles H. Moore(Forth創始者)

言語設計者たちが考えること (Theory in practice)

言語設計者たちが考えること (Theory in practice)


何かの原因で、トリッキーなことをした。
あとからコードを読む人は、その原因を知らないから、
「え、あれでやった方がいいのに」と考える。
そして、コードを変えてしまうと、バグが発生する。


そういうことを防ぐために、
「こういう原因があるから、あえてこうしているんですよ」
ということを説明するのが、コメントなんだ。


それが、引用にある「その意図、その意図を達成する上で用いている小細工」ということ。


コメントを書くのがえらいんじゃない。いいことなんじゃない。
意図を説明するために、書く必要があるコメントを書くのがえらいんだ。いいことなんだ。


みんなで、いいコメント書こうぜ!

P.S もうこういうのも止めなよ。SCMがあるんだから。これはノイズどころかゴミだよ。

// add jyukutyo 2011/11/17 start
...
// add jyukutyo 2011/11/17 end

// modify jyukutyo 2011/11/17 start
...
// modify jyukutyo 2011/11/17 end

// delete jyukutyo 2011/11/17 start
...
// delete jyukutyo 2011/11/17 end

全部消して、SCMで履歴を管理したらいい。