リーダブル・コードを読んで

エンジニアにとっては必読書となっている「リーダブル・コード」を読み、自分なりに要点をまとめておく。

とにかくコードは「読みやすい必要がある」ということがキーワード。 これは他の人、未来の自分含めて、読み手にとって分かりやすいコードであることが重要であるということが大前提として主張されている。

第Ⅰ部 表面上の改善

本部ではコードのロジックではなく見た目の部分にフォーカスして書かれている。

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

• 明確で正確な名前を付ける
• 単位（_secs 等）や重要属性（unescaped_ 等）を付ける
• 名前の長さはスコープの範囲に比例して許容

3章 誤解されない名前

• fillter より selectやexcludeを使う（fillterだと対象を選ぶのか除外するのかの2通りの取り方が出来てしまう）
• clip より remove や truncate を使う
• 限界値を含めるなら max min を使う
• 範囲指定なら first last を使う
• 包含・排他なら begin end を使う
• ブール値なら is has can should を使う
• 否定形より肯定形を使う

タイトル通り、誤解が生じたり、何通りかの取り方ができるような表現はしないようにして、なるべく取り方が万人共通になるように気をつけるということ。

4章 美しさ

• 一貫のあるレイアウト
• 似ているコードは見た目的にも似ているように見せる
• 関連するコードで段落を作る

コード全体でパッと見たときのわかりやすさや統一感を出そうという話。

5章

「コメントの目的は意図を伝えること」

逆説的に必要のないコメントは、 - コードからすぐ読み取れること - コメントのためのコメント

「ひどいコード + コメント」は「良いコード」に変えられるはず。

コメントすべきは下記のようなこと、

• 映画監督のコメンタリーの如く（自分の重要と思う考えを記録する）
• コードの欠陥を伝える
• 定数に対しての説明
• コードを見て疑問に思いそうなこと
• ファイルの最初に全体に対してのコメント（全体感を示すとか）
• 関数内部において、塊単位で要約するようなコメント

上記も非常に大切だが、結構今の自分に刺さったのが「コードを書いている過程で思ったことやメモ書きを一旦コメントとして残す → その後コメントを読み改善する」というフローがおすすめされていたこと。

これは結構迷いながらやることもあったので、背中を押された感覚で今後は積極的にやっていきたい。

6章

重要な考え「コメントは領域に対する情報比率が高くあるべき」

• コメントは完結に
• あいまいな代名詞は避ける
• 動作を正確に記述
• 入力値を実例で書くのも○
• コードの意図を書く
• 情報密度の高い言葉で

第Ⅱ部 ループとロジックの単純化

ここからはロジック等についての言及

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

「制御フローはなるべく自然であるべき」

例えば、if (length > 10)は、日本語的にも「lengthは10よりも大きい」とコードとの整合性があるので読みやすい。 なので、比較系では、左辺に比較対象（変化しやすい値）を持ってくると良い

• 条件文はなるべく肯定形を
• 単純な条件を先に書く
• 関心を引く条件や目立つ条件を先に書く
• 3項演算子は if / else より簡潔に書けそうなときだけ使う
• 関数では早く return する（複数のreturnはNGとする説もあるみたいだが、本書では否定的）
• ネストは浅く保つ

8章 巨大な式を分割する

キーワード「巨大な式は飲み込みやすい大きさに分割する」

コードを分割して、適宜簡潔な名前を付けた変数「説明変数」にする。これにより、

• コードが文書化される
• コードの主要概念が素早く読み取れるようになる

第9章 変数と読みやすさ

• 邪悪な変数を削除（コードを分かりやすくしてるわけでないもの、計算の結果を一時保存しているだけのもの）
• 変数のスコープを極力小さく
• constで複数回の書き込みは禁止する（イミュータブルにする）

第Ⅲ部 コードの再構成

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

「無関係の下位問題」とは、その文脈で高レベルの目標に対して効果がないもの。

例えば、日付をDBに保存するというのが目標のコードにおいて、「日付を表示用にフォーマットする」というのは直接高レベルの目標に対しての効果があるコードではない。

こうゆうコードは、可能なら抽出して別の関数にしたりするのが良い。

また、どんなプロジェクトでもよく使うような処理はユーティリティコードとして一括で管理したり、プロジェクト特有だが何度も使うようなコードは関数化して外部ファイル化しておく。

11章 一度に1つのことを

「コードは1つずつのタスクを行う」

読みにくいなと感じるコードがあれば、

• すべてのタスクを洗い出し列挙する
• 処理の塊でコードの段落を分ける
• 可能なものを関数化

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

プログラムを文章に起こして分かりやすく簡単な言葉で説明してみる。そしてそれをコードに反映する。

13章 短いコードを書く

「最も読みやすいコードは何も書かれてないコード」

コードは小さく保つことを心掛ける。そのために、

• 標準の機能やAPIを知って使う
• ライブラリ等使えるものは使う
• なるべく汎用コードをモジュール化

第Ⅳ部 選抜テーマ

14章 テストと読みやすさ

「安心してコードに変更を加えられるように、テストも分かりやすく書く」

• 本物のコードをテストしやすいように
• テストのトップレベルは極力簡潔に
• エラーメッセージは分かりやすく
• 単純な入力値を採用
• 何をテストしてるか分かりやすいテスト関数名にする（Test_<関数名>_<状況>等）