新人エンジニア必読書「リーダブルコード」 まとめ

1章 理解しやすいコード

読みやすいコードとは？
他の人が最短時間で理解できるコード
※コードが短くした方がいいが、理解するまでにかかる時間を短くする方が大事

2章 名前に情報を詰め込む

• 明確な単語を選ぶ

例えば、Getではなく、状況に応じてFetchやdownloadなどを使う

• 汎用的な名前を避ける

tmpやretvalなどの汎用的な名前を避ける。ただし、明確な理由があればOK

• 抽象的な名前よりも具体的な名前を使う

具体的な名前を使って、物事を詳細に説明する。例えば、ServerCanStart()よりもCanListenOnPort()の方が明確

• 接尾辞や接頭辞を使って情報を追加する

ミリ秒を表す変数名には、後ろに_msをつける。これからエスケープが必要な変数には、前にraw_をつける

• 名前の長さを決める

スコープが数画面に及ぶ変数に1-2文字の短い暗号めいた名前をつけてはいけない。短い名前はスコープが数行の変数につけるべきだ

• 名前のフォーマットで情報を伝える

大文字やアンダースコアなどに意味を含める。例えば、クラスのメンバ変数にアンダースコアをつけて、ローカル変数と区別する

3章 誤解されない名前

前提
名前が「他の意味と間違えられることはないだろうか？」と何度も自問自答する

• filter()
  →select()/exclude()

• clip(text, length)
  →truncate(text, max_chars)

• CART_TOO_BIG_LIMIT
  →MAX_ITEMTS_IN_CART

• 包括的な範囲を表す（=終端を範囲に含める）
  →first,last/min,max

• 包含/排他的範囲を表す（=終端を範囲に含めない）
  →begin,end

• boolの変数名はis, has, can, shouldを頭につける、否定形を避ける
  →bool HasSpeceLeft()

• get()
  →getで始まるメソッドはメンバの値を返すだけの「軽量アクセサ」

4章 美しさ

三原則
1.読み手が慣れているパターンと一貫性のあるレイアウトを使う
2.似ているコードは似ているように見せる
3.関連するコードをまとめてブロックにする

• 一貫性のある簡潔な改行位置
• メソッドを使った整列
• 縦の線をまっすぐにする
• 一貫性と意味のある並び
• 宣言をブロックにまとめる
• コードを「段落」に分割する
• 個人的な好みと一貫性

5章 コメントすべきことを知る

コメントの目的は、書き手の意図を読み手に知らせること

• コメントするべきでは「ない」ことを知る

  • コードからすぐにわかることをコメントに書かない
  • ひどい名前はコメントを付けずに名前を変える
    • 優れたコード　> ひどいコード + 優れたコメント

• コードを書いてる時の自分の考えを記録する

  • 「監督のコメンタリー」を入れる
    • コメントにはコードに対する大切な考えを記録する
    • なぜコードが他のやり方ではなくこうなっているのか
  • コードの欠陥にコメントをつける
    • TODO:あとで手を付ける(TODO=大きな問題、todo,maybe-later=小さな問題)
    • FIXME:既知の不具合があるコード
    • HACK:あまり綺麗じゃない解決策
    • XXX:危険！大きな問題がある
  • 定数にコメントをつける
    • 定数の値にまつわる「背景」

• 読み手の立場になって何が必要になるかを考える

  • 質問されそうなことを想像する
    • コードを読んで人が「えっ？」と思うところを予想してコメントをつける
  • ハマりそうな罠を告知する
    • 「このコードを見てびっくりすることは何だろう？どんなふうに間違えて違う可能性があるだろう？」と自分に問いかける
    • 平均的な読み手が驚くような動作は文書化しておく
  • 「全体像」のコメント
    • ファイルやクラスには「全体像」のコメントを書く
  • 要約コメント
    • コードをうまく要約したコメントをかく
    • 読み手が細部に囚われないようにコードブロックにコメントをつけて概要をまとめる

• ライターズブロックを乗り越える
  ライターズブロック＝行き詰まってしまって文章が書けないこと

  • 頭の中にあるコメントをとにかく書き出す
  • コメントを読んで改善が必要なものを見つける
  • 改善する

6章 コメントは正確で簡潔に

前提
コメントは領域に対する情報の比率が高くなければいけない

• コメントを簡潔にしておく

• 曖昧な代名詞を避ける

  • 複数のものを指す可能性がある「それ」や「これ」などの代名詞を避ける

• 歯切れの悪い文章を磨く

• 関数の動作を正確に記述する

• 入出力のコーナーケースに実例を使う

• コードの意図を書く

• 「名前付き引数」コメント

• 情報密度の高い言葉を使う

7章 制御フローを読みやすくする

前提
条件やループなどの制御フローはできるだけ自然にする。コードの読み手が立ち止まったり読み返したりしないように書く

• 条件式の引数の並び順
  左側：「調査対象」の式。変化する
  右側：「比較対象」の式。あまり変化しない

• if/elseブロックの並び順

  • 条件は否定系よちも肯定系を使う。例えば、if(!debug)ではなく、if(debug)を使う
  • 単純な条件を先に書く。ifとelseが同じ画面に表示されるので見やすい
  • 関心を惹く条件や目立つ条件を先に書く

• 三項演算子
  ※行数を短くするよりも、他の人が理解するのにかかる時間を短くする
  ※基本的にはif/elseを使う。三項演算子はそれによって簡潔になるときだけに使う

• do/whileループを避ける

• 関数から早く返す

• 悪名高きgoto

• ネストを浅くする

8章 巨大な式を分割する

前提
巨大な式は飲み込みやすい大きさに分割する

• 説明変数

  • 指揮を簡単に分割するには、式を表す変数を使えばいい
  • メリット
    • 巨大な式を分割できる
    • 簡潔な名前で式を説明することで、コードを文書化できる
    • コードの主要な「概念」を読み手が認識しやすくなる

• 要約変数

  • 大きなコードの塊を小さな名前に置き換えて、管理や把握を簡単にする変数のことを要約変数と呼ぶ。

• ド・モルガンの法則

  • not(a or b or c) ⇄ (not a) and (not b) and (not c)
  • not(a and b and c) ⇄ (not a) or (not b) or (not c)

• 短絡評価の悪用

  • 「頭がいい」コードに気を付ける。あとで他の人がコードを読むときにわかりにくくなる

• 式を簡潔にするもう一つの創造的な方法

9章 変数と読みやすさ

変数を適当に使うことで起きる問題

• 変数が多いと変数を追跡するのが難しくなる

• 変数のスコープが大きいとスコープを把握する時間が長くなる

• 変数が頻繁に変更されると現在の値を把握するのが難しくなる

• 変数を削除する

  • 役に立たない一時変数

  ✖️ now = datetime.datetime.now()
  root_message.last_view_time = now

  ○ root_message.last_view_time =　datetime.datetime.now()

  • 中間結果を削除する
  • 制御フロー変数を削除する

• 変数のスコープを縮める

10章 無関係の下位問題を抽出する

無関係の下位問題を積極的に見つけて抽出する

• 関数やコードブロックを見て「このコードの高レベルの目標は何か？」と自問する
• コードの各行に対して「高レベルの目標に直接的な効果があるのか？あるいは、無関係の下位問題を解決しているのか？」と自問する
• 無関係の下位問題を解決しているコードが相当量あれば、それらを抽出して別の関数にする

ユーティリティコード
→複数のプロジェクトで使えるあらかじめ用意しているようなコード。既存の関数がない場合、その関数を自分で書き、ユーティリティコードにする

• やりすぎに注意する
  • 小さな関数を作りすぎると逆に読みにくくなってしまう。あちこちに飛び回る実行パスを追いかけることになるから

11章 一度に１つのことを

前提
コードは一つずつタスクを行うようにしなければならない
読みにくいコードがあれば、そこで行われているタスクを全て列挙する。そこには別の関数（やクラス）に分割できるタスクがある。それ以外は、関数の論理的な「段落」になる。タスクをどのように分割するよりも、分割するということが大切。

1. コードが行なっている「タスク」を全て列挙する。この「タスク」という言葉はゆるく使っている。「オブジェクトが妥当かどうかを確認する」のように小さいなこともあれば、「ツリーの全てのノードをイテレートする」のように曖昧なこともある。

2. タスクをできるだけ異なる関数に分割する。少なくとも異なる領域に分割する。

12章 コードに思いを込める

おばあちゃんがわかるように説明できなければ、本当に理解したとは言えない By Albert Einstein

ラバーダッキング＝問題や設計をうまく言葉で説明できないのであれば、何かを見落としているか、詳細が明確になっていない。プログラム（あるいは自分の考え）を言葉にすることで明確な形になる。

コードをより明確にする簡単な手順

1. コードの動作を簡単な言葉で同僚にもわかるように説明する
2. その説明の中で使っているキーワードやフレーズに注目する
3. その説明に合わせてコードを書く

13章 短いコードを書く

前提
最も読みやすいコードは、何も書かれていないコード

• コードをできるだけ小さく軽量に維持するためには、
  • 汎用的な「ユーティリティ」コードを作って、重複コードを削除する
  • 未使用のコードや無用の機能を削除する
  • プロジェクトをサブプロジェクトに分割する
  • コードの「重量」を意識する。軽量で機敏にしておく

できるだけコードを書かないようにする。新しいコードには、テストや文書や保守が必要になる。また、コードが増えると「重く」なるし、開発も難しくなる。
新しいコードを書かないようにするには、

• 不必要な機能をプロダクトから削除する。過剰な機能は持たせない。
• 最も簡単に問題を解決できるような要求を考える。
• 定期的に全てのAPIを読んで、標準ライブラリに慣れ親しんでおく。

14章 テストと読みやすさ

前提
他のプログラマが安心してテストの追加や変更ができるように、テストコードを読みやすくする

起こり得る問題

• 本物のコードを修正するのを恐れる

• 新しいコードを書いたときにテストを追加しなくなる

• テストのトップレベルはできるだけ簡潔にする。入出力のテストはコード1行で記述

• テストが失敗したらバグの発見や修正がしやすいようなエラ〜メッセージを表示する

• テストに有効な最も単純な入力値を使う

• テスト関数に説明的な名前をつけて、何をテストしているのかを明らかにする。Test1()ではなく、Test_<関数名>_<状況>のような名前にする

15章 「分/時間カウンタ」を設計・実装する

※難しいのであとで読み直し

外部の視点を得る
外部の視点を得るというのは、コードが「ユーザーフレンドリー」かどうかを確認する優れた手段である。

解説

自然に読みやすいコードを書けるようになるための３つのステップ

• 実際にやる

  • 読む側ではなく書く側の視点でコードを見ているため、はじめはどこをよくすれば良いかを見つけることが難しい。リーダブルコードを読み直したり、仲間にコードを読んでもらったりしながら自分で「気づける」ようになることが大事。

• 当たり前にする

  • 一時的にコードを読みやすくしようというスタイルではなく、継続してコードを読みやすくしようというスタイルでコードを書く
  • 読みやすいコードを書くということはたまに思い出してやることではなく、習慣にして常に実践すること

• コードで伝える

  • コミットメール＝バージョン管理システム(Gitなど)に変更を追加（コミット）したときに送られる通知メール
  • diff入りのコミットメールを仲間に届くようにする
  • 改善案を読みやすいコードで伝える