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

読んだ本

• Amazon.co.jp: リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice) : Dustin Boswell, Trevor Foucher, 須藤 功平, 角 征典: 本

スクラップの内容

• 学習の記録として各章のまとめをもとに、情報を整理する

原則

• 誰もが（他人や将来の自分）理解しやすいコードであることが重要

2章「名前に情報を埋め込む」

• 明確な単語を選ぶ
• tmp(一時的な)やretval(戻り値)などの汎用的な名前を避ける
• 具体的な名前を使って、物事を詳細に説明する
• 変数めに大切な情報を追加する(_idとか)
• スコープの大きな変数には長い名前をつける
• 大文字やアンダースコアに意味を含める

別の参考資料

• Railsの命名規則に関わる内容だと下記資料が参考になる
  • コードレビューで学ぶ Ruby on Rails 第二版：SG Rails（pp.112~118）

3章「誤解されない名前」

• 上下の限界値：max,min
• 範囲を指定するとき：first,last
• 包含/排他的範囲（期間とか）：begin,end
• ブール値（TRUE または FALSE の真の値）：isやhasなどの名前と使う、否定系ではなく肯定系を使う：disable_sslではなくuse_ssl

4章「美しさ」

• 複数のコードで同じようなことをしていたらシルエットを同じようにする
• 一貫性のあるスタイル
• コードの列を揃えると概要が把握しやすくなり、タイプミスも見つかりやすくなる
• ある場所でABCで並んでいたものを、別の場所でACBとかCABとかにしない

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

コメントするべきじゃないこと

• コード読んですぐ分かること
• コメントのためのコメントをしない
• 説明が必要になるような命名はしない

コメントすべきこと

• コードが汚い理由、ちょっと変わった風な場合その意図
• コードの欠陥をかく
  | 記法 | 意味 |
  | ---- | ---- |
  | TODO: | あとで手をつける |
  | FIXME: | 既知の不具合があるコード |
  | HACK: | あまり綺麗じゃない解決策 |
  | XXX: | 危険！大きな問題がある |
• 定数にコメント（なぜその値にしたのか）
• 質問されそうなことを想像する
• ハマりそうな罠を告知する（注意点）
• 「全体像」のコメント・要約コメント

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

• 「それ」や「あれ」などの代名詞を使わない（わかりにくい）
• 関数の動作はわかりやすく説明する
• コードの意図は詳細レベルでなく、高レベルで記述する

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

比較の際便利な指針

• length >= 10 はあまりに見慣れすぎているが、10 <= length のようには書かないことからもわかる
• bytes_received < bytes_expectedが自然なのも、bytes_receivedは調査対象、bytes_expectedが比較対処だから

if/elseブロックの並び順

• 条件は否定系より肯定系を使う
• 単純な条件、関心を引く条件、目立つ条件を先に書く

三項演算子

• 基本は条件式で書いて、すっきりと書ける（条件が複雑でないときなど）時のみ使う

ネストは浅くする

• 早めに値を返す

9章「変数と読みやすさ」

• 邪魔な変数は削除
• 変数のスコープはできるだけ小さくする
• 一度だけ書き込む変数を使う

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

考えること

1. 関数やコードブロックを見て「このコードの高レベルも目標は何か？」と自問する
2. コードの各行に対して「高レベルの目標に直接的な効果があるのか？　あるいは無関係の下位問題を解決しているのか？」と自問する
3. 無関係の下位問題を解決しているコードが相当量あればそれらを抽出して別の関数にする（「相当量とは？」→あまり細かすぎても逆にわかりにくくなる）

下位機能をメソッドとして切り離す

• 正規表現や文字列処理の箇所を別で切り分けることによりコードが読みやすくなる
• グルーコードも同様に切り離すことができる

知らない言葉

グルーコード（英: glue code）：コンピュータプログラミングにおいてプログラムの要求仕様の実現には一切寄与しないが、もともと互換性がない部分同士を結合するためだけに働くコードである（参考：グルーコード - Wikipedia）

まとめ

• プロジェクト固有のコードから汎用コードを分離する

11章「一度に１つのことを」

やること

• 読みにくいコードがあればそのコードで実行しているタスクを列挙する
• 必要に応じて分割する。分割できない場合は関数の論理的な段落になる。

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

手順

1. コードの操作を簡単な言葉で同僚にもわかるように説明する
2. その説明の中で使っているキーワードやフレーズに注目する（分割する下位問題がなんであるか分かる）
3. その説明に合わせてコードを書く

• 人間が流れを汲み取りやすいコードになる

13章「短いコードを書く」

理由

• コードが長ければ長いほど実装に労力がかかるし、デバックにも時間がかかる

方法

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

解説

• 実際に書いてみる
• 他の人に読んでもらう
• そのことを当たり前にする