读书笔记-リーダブルコード

Posted on Edited on In

《リーダブルコード》读书笔记
The Art of Readable Code

1 理解しやすいコード

読みやすさの基本定理：コードは他人が最短時間で理解できるように書かなければいけない。

2 名前に情報を詰め込む

明確な単語を選ぶ

  • 気取った言い回しよりも明確で正確な方がいい

汎用的な名前を避ける

  • tmp/retvalなど空虚な名前
  • あるいは、使う状況を選ぶ
  • ループイテレータ：i/j/k/iterなどより、もっと明確な説明的な名前のほうがよい(e.g. users_i, members_i)

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

名前に情報を追加する

  • 名前は短いコメントのようなものだ
  • 追加する情報例：フォーマット、単位、危険や注意喚起する情報など

名前の長さを決める

  • スコープが小さなければ短い名前でもいい
  • 長い名前を入力するのは問題じゃない
  • 頭文字と省略形(新しいチームメイトはその名前の意味を理解できるだろうか？)
  • 不要な単語を投げ捨てる

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

  • CamelCase、lower_separated、CONSTANT_NAMEなど

3 誤解されない名前

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

範囲について

  • 限界値を含めるときは min/max を使う
  • 範囲を指定するときは first/last を使う [first, last]
  • 包含／排他的範囲には begin/end を使う [begin, end)

ブール値の変数名は頭に is/has/can/should などをつけてわかりやすくする

4 美しさ

一貫性と意味のあるやり方でコードを整形する

  • 複数のコードブロックで同じようなことをしていたら、シルエットも同じようなものにする
  • コードの「列」を整列すれば、概要が把握しやすくなる
  • ある場所でA/B/Cのように並んでいたものを、他の場所でB/C/Aのように並べではいけない。意味のある順番を選んで、常にその順番を守る
  • 空行を使って大きなブロックを論理的な「段落」に分ける

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

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

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

  • コードからすぐにわかること
  • ひどいコードを補う「補助的なコメント」。コメントを書くのではなくコードを修正すべき（優れたコード>ひどいコード+優れたコメント）

記録すべき自分の考え

  • なぜコードが他のやり方ではなくこうなっているのか
  • コードの欠陥をTODO:などの記法を使って示す
  • 定数の値にまつわる「背景」

読み手の立場になって考える

  • コードを読んだ人が「えっ？」と思うところを予想してコメントを付ける
  • ハマりそうな罠を告知する、平均的な読み手が驚くような動作は文書化しておく
  • ファイルやクラスには「全体像」のコメントを書く
  • 要約コメント。読み手が細部に捕まられないように、コードブロックにコメントをつけて概要をまとめる

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

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

あいまいな代名詞を避ける

歯切りの悪い文章を磨く

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

コードの意図を書く。詳細レベルではなく、高いレベルで記述する

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

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

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

条件式の引数の並び順

  • 左側：「調査対象」の式。変化する。
  • 右側：「比較対象」の式。あまり変化しない。
  • e.g. while (bytes_received < bytes_expected)

if/else ブロックの並び順

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

三項演算子

  • 行数を短くするよりも、他の人が理解するのにかかる時間を短くする。

do/while ループを避ける

関数から早く返す

  • ガード節：関数の上部で単純な条件を先に処理するもの

ネストを浅くする

  • 変更するときにはコードを新鮮な目で見る。一歩下がって全体を見る。
  • 早めに返してネストを削除する。
  • ループ内部のネストを削除する。

8 巨大な式を分割する

説明変数、要約変数

  • 簡潔な名前で式を説明することで、コードを文書化できる。
  • コードの主要な「概念」を読み手が認識しやすくなる。

ド・モルガンの法則

短絡評価の悪用を注意する

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

9 変数と読みやすさ

変数を削除する

  • 役に立たない一時変数
  • 中間結果
  • 制御フロー変数

変数のスコープを縮める

  • 変数のことが見えるコード行数をできるだけ減らす
  • 分割、ネットする／しないスコープ、定義の位置を下げるなど

変数は一度だけ書き込む

  • 変数を操作する場所が増えると、現在値の判断が難しくなる

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

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

ユーティリティ／汎用コードを分離する。プログラムに固有の小さな核だけが残る。

ラッパー関数

理想とは程遠いインタフェースに妥協することはない。自分でラッパー関数を用意して、手も足も出ない汚いインタフェースを覆い隠す。

11 一度に1つのことを

タスクは小さくできる、分割する

関数の論理的な「段落」になる

12 コードに思いを込める

コードをより明確にするため

  1. コードの動作を簡単な言葉で同僚にもわかるように説明する（ロジック）
  2. その説明のなかで使っているキーワードやフレーズに注目する
  3. その説明に合わせてコードを書く（ライブラリのメソッドを活用）

13 短いコードを書く

不必要な機能をプロダクトから削除する。過剰な機能は持たせない。

最も簡単に問題を解決できるような要求を考える。

定期的にすべでのAPIを読んで、標準ライブラリに慣れ親しんでおく。

コードをできるだけ小さく軽量に維持する

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

14 テストと読みやすさ

一般的な設計原則として、「大切ではない詳細はユーザから隠し、大切な詳細は目立つようにする」べきだ

最小のテストを作る

  • テストのトップレベルはでいるだけ簡潔にする。入出力のテストはコード1行で記述できるといい
  • テストに有効な最も単純な入力値を使う

デバッグに使える情報

  • エラーメッセージを読みやすくなる、できるだけ役に立つようにする
  • テストの機能に名前をつける

複数のテストで別々の方向からバグを見つけ出すようにする

  • 分割、疎結合