はじめに

「リーダブルコード」はオライリー社が出版する、コーディングテクニックをまとめた技術書である。
言わずと知れた名書であり、たびたび知人や技術系のサイトで紹介されてはいたが、なかなかちゃんと読む機会がなかったので、この際に備忘録を兼ねてまとめながら読んでいこうと思う。

ちなみに原書タイトルは Dustin Boswell, Trevor Foucher による "The Art of Readable Code" である。
原書タイトルには "The Art" の文字が...コーディングにおける美しさは芸術であるということを示唆しているのだろうか...

構成

【今回取り扱う内容】
   - 1章 理解しやすいコード
- Ⅰ部 表面上の改善
   - 2章 名前に情報を詰め込む
   - 3章 誤解されない名前
   - 4章 美しさ
   - 5章 コメントすべきことを知る
   - 6章 コメントは正確で簡潔に
-------------------
(本稿以降の内容)
- Ⅱ部 ループ/ロジックの単純化
- Ⅲ部 コード再編成
- Ⅳ部　選抜テーマ

全体として4個の部から構成されており、難易度順に章立てがされている。
著者は1~2週間程度での読了を推奨しており、楽しく気楽に読むことを推奨している。

内容

独断によるⅠ部全体 超要約

• 「パット見」で分かるコードが良いコード。
• 関数/変数名に明瞭な情報を組み込むことで、不要なコメントを削減し、コード全体を簡潔にする。
• 簡潔にしたコードは類似処理や手順毎にまとめ、見た目にズレがない様に体裁を整える。
• 全体観を意識した上で、気になる箇所や罠となるポイントにコメントを残す。

章ごとの要約

オレンジ色の文字は、意識しなけばいけない内容
紫色の文字は、具体的な対策方法

序章

1章：目的

• 「優れた」コードとは、
  《理解しやすいコード = 読みやすいコード = 他者が最短時間で理解できるコード》である
• コードを書く上での優先度は、
  《理解のしやすさ > コードの短さ》である。
  短いが複雑で分かりづらいコードよりも、分かりやすいコードのほうが好まれる。

Ⅰ部 表面上の改善

2章：名前に情報を詰み込む

• 類義語辞典等を使い、明確な単語（"カラフル"な単語）を選ぶ
• 意味がある変数には、汎用的で情報のない空虚な名称（tmp/retvalなど）をつけない
• ループイテレータが複数存在する場合は、ループ箇所名を組み込んだ名称 にするとよい
• 「何を」「どうする」のか、動作や目的を示す具体的な名称にするとよい
• 単位や属性、型の情報（ハンガリアン記法）を組み込むとよい
  • ハンガリアン記法に関しては否定的な意見が多く、吟味する必要がある
    (Qiita記事「ハンガリアン記法 メモ」等参照）
  • 著者はハンガリアン記法まで厳格ではない、規律の緩い「イングリッシュ記法（造語）」を推奨
• 名称の長さはスコープの長さ で判断する（スコープが短ければ、短い名称でもOK）
• 一般的に知られている省略形なら使用しても良い（String->strなど）
• 不要な情報は記載しない。必要なものだけ。

3章：誤解されない名前

• 文字の大小で利用する場所を区別する（ローカル変数/グローバル関数）
• 曖昧な意味の単語は用いない
  • 制限関連なら limit ではなく min/max を用いる
  • 範囲指定なら first/last, begin/end を用いる（それぞれ包括/排他的意味[以下/未満]が異なる）
  • ユーザが期待する処理を行うべきである
    ("get","size"のように軽量アクセサで重い処理を行ってはいけない。"compute"等に変更する。)
  • プロトタイプ継承パターンのような場合に、抽象性の高い"template"を用いるのではなく、
    "inherit(_from_experiment)"のような名称を用いる

4章：美しさ

• 優れたソースコードは「目に優しい」コード
• 《プログラミング時間の大半はコードを読む時間》である
• 読みやすいコード「余白・配置・順序の3原則」
  1. 読み手が慣れているパターンと一貫性のあるレイアウトを使う
     • 変数名の長さ等も考慮して、改行位置を合わせる
     • 変数の順番は可視化順、重要度順、アルファベット順に整える
  2. 似ているコードは似ているように見せる
     • 空白を用いることで縦のラインをまっすぐに合わせる
  3. 関連コードはまとめてブロック化する
     • 細かなコードをまとめてメソッド化する(ヘルパーメソッドを用いる)ことで、
       パッと見で流れが理解しやすくなり、コード追加が楽になる
     • 類似メソッドはブロックごとにまとめて、段落ごとに区切る
     • 同じコメントは一ヵ所にまとめて書く
       

同じコメントは一ヵ所にまとめて書く
e.g. 同じコンストラクタを用いたインスタンスが何度も繰り返される場合

-----------------------------

【悪い例】
instance1 =
new constructor(
    a1, // aの引数
    b1, // bの引数
    c1, // cの引数
    d1, // dの引数
)

instance2 =
new constructor(
    a2, // aの引数
    b2, // bの引数
    c2, // cの引数
    d2, // dの引数
)
...

-----------------------------

【良い例】
// new constructor(aの引数, bの引数, cの引数, dの引数)
//                 [kbps]   [ms]   [percent]

instance1 = new constructor(a1, b1, c1, d1)
instance2 = new constructor(a2, b2, c2, d2)

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

• 《コメントの目的は書き手の意図を読み手に伝えることである》
• コメントに関する話題3つ
  1. コメントするべきでは「ない」ことを知る
     • コードからすぐにわかる情報は記載しない
     • 抽象的な(酷い)名称をつけられた関数の、補足説明をする場所ではない
     • 通常、コードの読みにくさを補うコメントは必要ない
       「優れたコード」 > 「酷いコード + 優れたコメント」
  2. コードを書いているときの自分の考えを記録する
     • 「優れたコメント」 = 「考えを記録する」ためのもの
     • "TODO:","todo:","maybe-later:"等の記号をコメントに入れることで、コードの欠陥/修正箇所を文章化しておく
     • 定数の定義時に、理由や背景を記載することで、調整する必要性の有無を周知する
  3. 読み手の立場になって何が必要になるかを考える
     • 間違えやすい場所や疑問に思われやすい箇所には、事前にコメントに記載する
     • 全体像について書く
     • ライターズブロックを乗り越え、とりあえずコメントする(6章:書き方のコツへと繋がる)

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

• 簡潔に記載する
• 代名詞は避ける
• 文章を磨く(回りくどく言わず、直接的に言い切る)
• 抽象的な内容ではなく、正確な処理を記載する
  • 実例を用いても良い
  • 処理を行うことで、何をなし得たいのかを記載する
• 情報密度の高い言葉を用いる

あとがき

自分は現段階ではこれ以上、本書の内容をまとめることができない気がする。
実際にもっとコーディングを行い、その経験を踏まえた上で内容理解を深めた方が良いと感じたため、一旦これにて記事投稿。
何か気付きがあればその都度、随時記事を更新していこうかと思います。

参考サイト

• リーダブルコードを読んだので、殴り書き
• リーダブルコード要約とリーダブルコード要約の活用方法
• FPGA開発日記
• 「読んですぐ伝わる文章」の3大条件