すぐ使える！初心者が知るべき「リーダブルコード」のポイントまとめ

はじめに

本稿は「The Art of Readable Code: Simple and Practical Techniques for Writing Better Code (O'Reilly Media)」を読んで、プログラミング初心者である私が感じた、すぐに活かせそうな考え方・ポイントをまとめたものです。

他の要約記事と異なるのは、初心者である私の立場から、すぐに適用できそうだと感じた項目をまとめている点です。読書で重要なのは、書かれている内容を「できることから実践する」ことだと思っているので、私以外の初心者の方もすぐに実践できそうなポイントをまとめてみました。そのため、基礎的な内容が多い前半の項目（6章まで）に限定しています。

日本語版では「リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック（オライリー・ジャパン）」として有名な本著ですが、私はACM会員特典のSafari Books Onlineという技術書読み放題のサービス（英語のみ対応）を利用して読んだため、英語版の内容となっています。

ACMについて詳しく知りたい方は以下をご参考ください。
【参考】
ACM Professional Membershipの登録
年99ドルでオライリーの英語技術書を読み放題にする方法

コードは理解しやすいものでなければならない

Code should be easy to understand.
(Chapter 1. Code Should Be Easy to Understand)

リーダブルコードで書かれている様々なポイントは、この目的に集約されます。全ては理解しやすいコードを書くため。同じチャプター内では、例を交えた上で以下のようにも言い換えられています。

Code should be written to minimize the time it would take for someone else to understand it.
(Chapter 1. Code Should Be Easy to Understand)

コードは他人が理解するのにかかる時間が最小限で済むように、ということです。このコードが長いから悪い、短いから良い、という話ではなく、「このコードは他人が見たときにすぐに理解できるか？」ということ
を判断基準にして、コードを客観的に見ていく必要があるんですね。

名前に情報を詰める

Whether you’re naming a variable, a function, or a class, a lot of the same principles apply. We like to think of a name as a tiny comment. Even though there isn’t much room, you can convey a lot of information by choosing a good name.
(:Chapter 2. Packing Information into Names)

【訳】
変数や関数、クラスなど何の命名にせよ、同じ原則の多くが適用されます。名前を小さなコメントだと考えましょう。大きなスペースはないけれど、良い名前を選ぶことで多くの情報を伝えられます。

命名が必要な時、あまり深く考えずに名前を決めてしまっていましたが、気をつけたいポイントですね。自分が理解できる名前かどうか？という基準で私は命名してしまいがちだったのですが、初めて見る人がすぐに理解できるような名前をつけるよう気をつけなければいけないと気付かされました。

また、以下に具体的な命名方法についても述べられています。

1. 具体的な名前をつける

Part of “packing information into names” is choosing words that are very specific and avoiding “empty” words.
(Chapter 2. Packing Information into Names)

【訳】
「情報を名前に詰める」ことの一つは、非常に具体的な名前を選び、内容のない言葉を避けるということです。

例えば以下のようにコードがあるとして

class Thread {
    void Stop();
    ...
};

void Stop()でも問題ありませんが、Kill()のほうがより詳細ですし、もしResume()があるのであれば対応するようなPause()も良いだろうと説明されています。

2. もっと「カラフル」な言葉を見つける

Don’t be afraid to use a thesaurus or ask a friend for better name suggestions. English is a rich language, and there are a lot of words to choose from.
(Chapter 2. Packing Information into Names)

【訳】
類語辞典を使ったり、より良い名前がないか周りの人に聞くことを恐れないでください。英語は豊富な言語ですから、言葉の選択肢はたくさんあります。

ここでいう「カラフル」というのは、「詳細である」と同義でしょう。私達は日本人ですが、命名は英語で行いますよね。英語ネイティブの人たちに比べると、ボキャブラリーが乏しい私達はなおさら辞典を使って適切な単語を選択する努力をしなければいけないですね。最初は大変かもしれませんが、プログラミングで行われる処理にはある程度共通性があるので、よく使われるボキャブラリーをある程度蓄積できれば、それほど苦労せずに「カラフル」な単語を使えるようになるのかなと思います。

3. 名前はどれぐらいの長さであるべきか？

This decision is a judgment call whose best answer depends on exactly how that variable is being used.
(Chapter 2. Packing Information into Names)

【訳】
これは主観的な判断になります。ベストな答えは、その変数がどう使われてるかに完全によります。

その変数がどう使われているかの具体的な例と、それに対する回答も述べられています。

① 使われる範囲が狭ければ名前も短くて良い

When you go on a short vacation, you typically pack less luggage than if you go on a long vacation. Similarly, identifiers that have a small “scope” (how many other lines of code can “see” this name) don’t need to carry as much information.
(Chapter 2. Packing Information into Names)

【訳】
短い休暇に行く時、長い休暇のときよりも少ない荷物を詰めますよね。それと同じように、範囲（他の行でどれだけその名前が現れるか）が狭い識別子であれば、それほど多くの情報は詰める必要はないでしょう。

変数の有効範囲が短ければ、その変数が何を表しているのかは容易に理解できるはずなので、たくさんの情報は詰めなくても良いとしています。

② 長い名前はもはや大した問題ではない

There are many good reasons to avoid long names, but “they’re harder to type” is no longer one of them. Every programming text editor we’ve seen has “word completion” built in.
(Chapter 2. Packing Information into Names)

【訳】
長い名前を避けるのに十分な理由は多くありますが、「タイピングするのが大変」というのはもはや理由になりません。私がこれまで見てきたどのテキストエディターでも「単語補完」機能が標準搭載されています。

そのため、極端な長さで可読性に影響を与えるレベルでなければ単語の長さはそれほど気にかける必要はないということですね。個人的には三語以上からなる名前だと「長すぎるかな？」という印象でしたが、それを省略することで必要な情報が削がれるようであれば、名前が長くなることは妥協してもいいのかもしれないですね。

美学を持つ

Obviously it’s easier to work with code that’s aesthetically pleasing. If you think about it, most of your time programming is spent looking at code! The faster you can skim through your code, the easier it is for everyone to use it.
(Chapter 4. Aesthetics )

【訳】
美しいコードの方が扱いやすいのは明らかです。考えてみれば、プログラミングの時間の大半はコードを見ることに使っているでしょう。早く目を通すことできるコードであればあるほど、みんなにとっても使いやすいコードなわけです。

ここでいう美学というのは、どれだけ見やすいコードであるか、ということですね。インデントを整える、名前に統一性をもたせるなど、自分で感覚的に理解していることは実践しているつもりでしたが、他にも多くの知見が紹介されていました。

1. 意味のある順序を選び、一貫性を持たせる

(...) , it’s helpful to put them in some meaningful order, not just random.
(...)
Whatever the order, you should use the same order throughout your code.
(Chapter 4. Aesthetics )

【訳】
それら（識別子）を適当な順番ではなく、意味のある順番に配置することは役に立ちます。
(...) どの順番を使うにせよ、同じ順番をコードの中で使うべきでしょう。

本著の中では、「重要度で並べる」、「アルファベット順で並べる」などいくつかの案が提示されていますが、大切なことは同じルールを用いて一貫性を持たせるということですね。正直このレベルで変数や関数の宣言順を意識できていませんでした。確かに一貫線をもたせることで、読み手は様々な点で利点がありますよね。

2. コードをパラグラフに分ける

Code should be broken into “paragraphs” for the same reasons. For example, no one likes to read a giant lump of code like this:
(Chapter 4. Aesthetics )

【訳】
(...)同じ理由から、コードはパラグラフに分けるべきです。例えば、こんな大きな塊のコードは誰も読みたくないでしょう。

# Import the user's email contacts, and match them to users in our system.
# Then display a list of those users that he/she isn't already friends with.
def suggest_new_friends(user, email_password):
    friends = user.friends()
    friend_emails = set(f.email for f in friends)
    contacts = import_contacts(user.email, email_password)
    contact_emails = set(c.email for c in contacts)
    non_friend_emails = contact_emails - friend_emails
    suggested_friends = User.objects.select(email__in=non_friend_emails)
    display['user'] = user
    display['friends'] = friends
    display['suggested_friends'] = suggested_friends
    return render("suggested_friends.html", display)

It may not be obvious, but this function goes through a number of distinct steps. So it would be especially useful to break up those lines of code into paragraphs:
(Chapter 4. Aesthetics )

【訳】
少しわかりにくいかもしれませんが、この関数はいくつもの明確なステップを経由しています。そのため、これらのコードをパラグラフ（段落）に分けることは特に有用でしょう。

def suggest_new_friends(user, email_password):
    # Get the user's friends' email addresses.
    friends = user.friends()
    friend_emails = set(f.email for f in friends)

    # Import all email addresses from this user's email account.
    contacts = import_contacts(user.email, email_password)
    contact_emails = set(c.email for c in contacts)

    # Find matching users that they aren't already friends with.
    non_friend_emails = contact_emails - friend_emails
    suggested_friends = User.objects.select(email__in=non_friend_emails)

    # Display these lists on the page.
    display['user'] = user
    display['friends'] = friends
    display['suggested_friends'] = suggested_friends

    return render("suggested_friends.html", display)

処理を単位に分けて、コメントを添えてあげることでわかりやすくなりますね。小さな関数では必要ないかもしれませんが、この程度の規模になると非常に見やすくなると思います。

何をコメントするべきか知る

The purpose of commenting is to help the reader know as much as the writer did.
(Chapter 5. Knowing What to Comment)

【訳】
コメントをつける目的は、書き手が理解していることをできるだけ読み手にも知ってもらうのを助けるためです。

1. コメントすべきでないこと

Don’t comment on facts that can be derived quickly from the code itself.
(Chapter 5. Knowing What to Comment)

【訳】
コード自体からすぐにわかるような事実についてコメントをつけない

# remove everything after the second '*'
name = '*'.join(line.split('*')[:2])

上記の例では、コメントから新たな情報は何も得られないため、不要としています。ただ、大半のプログラマーにとっては、コメントがついたコードを読むほうが、コメント無しのコードを読むよりずっと早く理解できるとも述べられています。
また、良いコメントをつけることよりも良い名前をつけることのほうが重要だとしています。それは、識別子（変数や関数）の名前はいたるところで現れますが、コメントはコメントをつけたところでしか見られないからですね。

2. 考えを記録する

A lot of good comments can come out of simply “recording your thoughts”—that is, the important thoughts you had as you were writing the code.
(Chapter 5. Knowing What to Comment)

【訳】
良いコメントの多くは、単純に「考えを記録する」ことから出てきます。それはつまり、コードを書いていた時の重要な考えを記録するということです。

// This class is getting messy. Maybe we should create a 'ResourceNode' subclass to
// help organize things.
(訳：このクラスは汚くなってきている。"ResourceNode"サブクラスを作って整理したほうがいいかも。)

上記の例では、書き手のコードに対する考えを記録しています。ここから、読み手にもクラスの改修が必要なことを示唆してくれていますね。このコメントがなければこのクラスを使う人達は、ぐちゃぐちゃなクラスを触りたくないと思ってしまうかもしれません。
これと同じように、自分のコードの問題点を記載することで読み手にも意識させることができると述べています。

この章で述べられていることは、とにかく「読み手の立場に立つ」ということです。
読み手が書き手と同じぐらいコードを理解できるように、コードの問題点や、このコードが何をしているのか、使う際にどんな注意が必要か、などなど、詳細をコメントすることの重要性が説明されています。

おわりに

自分は重要点だけかいつまみながら、最後まで本書を読みました。個人的に読んで良かったと思うのは、感覚的になんとなくやっていた自分の書き方が、こういう時はこうするといい、というパターンが明文化されていて、頭の中で理由とともに整理されたことです。

現在ポートフォリオ作りに励んでいる私ですが、早速今作ってる作品のコードで実践していきます。リーダブルコードで学んだことを自分のコードで適用してみたらどうなったか、的な記事も書いてみたら面白そう。

参考

The Art of Readable Code: Simple and Practical Techniques for Writing Better Code