Route 477

■ [prog] コメントの話

去年くらいから仕事のコードでは、privateも含めて全部のメソッドに「何をするメソッドか」という簡単な説明を書くように心がけています。 こういうやつですね。

  # このレコードの種類を文字列で返す
  # 種類が未定義の場合はnilを返す
  def type_name
    FOO_NAMES[self.foo_type] 
  end

理由をメモ的にまとめておきます。

1. コメントがあると読む人が助かる

バグ修正や機能追加とかで、コードを読む機会というのはけっこうある。そういうときにメソッド単位でコメントがあるとすごく助かる。*1 1行書いておくだけで情報共有のコストが下がるなら、充分良い投資ではないかと思います。

あるいはメソッドを短くして適切なメソッド名を付ければ、コメントは要らないのではと考えたこともあるけど、本当に意図がソースから自明になることって少ないんですよね。例えば上の例でも実装は1行だけど、コーナーケースについて実装者がどう考えているのかは自明ではない。

2. コメントが設計を助ける

メソッドの説明を書くことにすると、おのずと「このメソッドは何を行うのか」というのを考えさせられる。 すると例えば「Aを取得してBをする」って書こうとしたところで「あれ、これAが存在しない場合も考える必要があるな」とか、設計の間違いに気づくことがままある。

3. 「何をしようとしたか」が残る

例えばレビューをするとして、コメントがあれば「このメソッドは実際にどう振る舞うか(A)」だけでなく、「このメソッドで何をしようとしたのか(B)」についてもチェックすることができる。 しかしメソッドの説明がないと、当人はなにか勘違いをしてるのだけど結果的に動くコードになっている場合 (=Aは正しいがBが間違っているケース) について指摘ができない。

補足

まあ規約にするかどうかはチームによるかなと思います。コメント無かったら気づいた人が足すというのとかでも良いと思うし。

あと趣味のコードに関しては上記の限りではないです(免責)*2