| @技術/プログラミング
最近、会社でリーダブルコードを輪読したり、Fukuoka.rb で Eloquent Ruby を読んだりしていて、メソッドや変数名の長さやコメントについての議論を読む機会があった。昨日、たまた...

最近、会社でリーダブルコードを輪読したり、Fukuoka.rb で Eloquent Ruby を読んだりしていて、メソッドや変数名の長さやコメントについての議論を読む機会があった。

昨日、たまたま 37signals のブログを読んでいたら、Rails の作者である David Heinemeier Hansson もこのトピックについて書いていた。

自分は WEB+DB PRESS で ukstudio さんの書いた RSpec についての記事を読んで感化されて以来、ソースコード中のコメントはすべて悪で、はっきりしたメソッド名、変数名を使えばコメントはいらないという考え方を持っている。DHH もそのような考え方のようだ。

Clarity over brevity in variable and method names

Clarity over brevity in variable and method names

Many programmers have a natural preference for short variable and method names. I doubt many would recognize this preference as a trade of brevity for clarity, but that’s often exactly the result. This is especially true if you subscribe to the ridiculous Church of 80-character Lines. It n…

37signals.com

要点をかいつまむ。

多くのプログラマーは短い変数名やメソッド名を好む。短い命名は明確性や簡潔性を犠牲にしているとみんな気づいてるんじゃないかと疑ってるんだけど、実際のところ短い命名を採用したコードが多い。特に「一行は80文字まで」教の連中に。

しかし最近のプログラミング言語は表現豊かなのだから、短い命名にこだわる必要は無い。

extension を ext と略してあるのを見かけると嫌気がさす。アプリケーション固有の略語を作るのはもっとひどい。そんなの二ヶ月後には絶対忘れてる。

過剰に明瞭な名前は一見するとバカっぽい。処理内容よりもメソッド名の方が長いとかね。でも一発でやってる内容が分かることの前ではそのバカっぽさは霧消する。

最近の Basecamp のコードにはこんなのがある。

def make_person_an_outside_subscriber_if_all_accesses_revoked
  person.update_attribute(:outside_subscriber, true) if person.reload.accesses.blank?
end

def shift_records_upward_starting_at(position)
  positioned_records.update_all "position = position - 1",
    ["position >= ?", position]
end

def someone_else_just_finished_writing?(document)
  if event = document.current_version_event
    !event.by_current_creator? and event.updated_at > 1.minute.ago
  end
end

もし十分に明確な命名をしているのであれば、コードにコメントを書く必要がない。コメントというものは往々にして不明瞭な命名をしているコードの中で必要になる。コメント付きのコードはやばい臭いを放っていると思っといた方がいい。

コメントはいらない

リーダブルコードの中にも「名前は短いコメントだと思えばいい」というくだりがあるけど、基本的にあの本には「いいコメントを書け」と書いてあるような気がする。コメントそのものを悪いとみなしていない。

先々週読んだ Eloquent Ruby の Chapter 8. Embrace Dynamic Typing の中では Ruby という言語の特性も踏まえ、コメントはいらないと書いてあった。

例えば Ruby ではメソッド名の最後にはてなをつけてあると Boolean を返すという慣習がある。だからコードの中に「○×を判定し true/false を返します」というようなコメントはいらない。

def is_longer_than?(number_of_characters)
  @content.length > number_of_characters
end

Eloquent Ruby は Chapter 1 でもコメントについて述べている。そこには「コメントを書くべき理由があるコードもある」と書いてある。そのコードの使い方を指南したコメントだ。「なぜそのようなコードを書いたのか」、「コード内で用いているアルゴリズムの説明」、「どのようにして高速化したか」というようなことは書くべきではないと言っている。この辺はリーダブルコードと正反対だ。リーダブルコードでは「なぜそのような実装にしたのか」を積極的に書くように奨励されていた。

ちょっと前にはてブでホッテントリに入ってた、ソースコード内のコメントでコードレビューをやるというやり方は最悪だと思う。売り物のコードの中でああでもないこうでもないと議論するなんて狂ってる。コードが修正されたときに議論の内容まで適切に修正されるとは思えない。下手をするとコメントとコードの内容が正反対になってしまうかも知れない。コードの背景についてはコード内に書かず、GitHub 使ってインラインコメントでやった方が良いと思う。

皆さんはどう思いますか?

Comments


(Option)

(Option)