リーダブルコード Part1

1. 可読性について
PART1(表面上の改善)

2. なぜ可読性が必要なのか？
動かすのはPCだが、「読むのは人間」であり、
プログラミングのほとんどの時間はコード読む時間であるため

3. 可読性が低いと何が起きるのか？
・読んで理解するまでに時間がかかる
イコール実装までに余計な工数がかかる
・バグが混入しやすい
この変数はどんな値が入っているのが正解なのか？
この関数はどんな値が返ってくる関数なのか？
・デバッグに時間がかかる
・改修や変更に時間がかかる

4. 今回参考にする書籍

5. そもそも読みやすいとは？
・読みやすさの基本定理
第三者が自分のコードを読んで理解する時間を最短にすること
・優れたコードとは？
「読みやすい」コードを書くことは、
「理解しやすい」コードを書くことであり、
その結果として「優れた」コードに繋がる
・理解するとは？
変更を加えたり、バグを見つけたりできること

6. リーダブルコードで書かれている改善策
- 表面上の改善策
- 適切な名前
- 優れたコメント
- フォーマット
- ループとロジックの単純化
- 制御フローを読みやすくする
- ネストを浅く
- 早期return
- コードの再構成
- 1度に1つのことを(単一責任の原則)
- 短いコードを書く(KISSの原則/YAGNIの原則)

7. 今回取り上げる改善策 PART1
・適切な名前
・目に優しい美しさ
・コメントすべきこと/すべきで「ない」こと

8. - 命名
- 明確で正確な単語を選ぶ
- getSize() => getHeight()
- get/fetch/download 状況によって適切で明確なものを選ぶ
- 汎用的な名前は避ける
- retval => sumSquares
- ただし、情報の一時的な保管で生存期間が短いケースでは汎用的な名前が役に立
つこともある(ループイテレータなど)
- 抽象的な名前よりも具体的な名前を使う(例：値の単位など)
- delay => delayMs
- 重要な属性を追加する
- password => plaintextPassword
- comment => unescapedComment
- 全てに属性を追加するのではなく、「バグ」の元になりそうな所へ追加する
適切な名前（命名）

9. 適切な名前（誤解されない名前）
- 誤解されない名前
- filter = 濾過する
- filterは条件にあったものを「選択(select)」なのか「除外(exclude)」なのか不明確
- 限界値はmin/maxを使う
- 未満(限界値を含まない)なのか以下(限界値を含む)なのか
- booleanはis/has/can/shouldを使う
- trueとfalseの意味を明確にするため

10. 美しさ
- なぜ美しさが必要なのか
- 優れたコードは目に優しく、見た目が美しいコードの方が使いやすい
- 美しさと優れた設計は関連しており、リファクタリングがうまくいくようになる
- 3つの原則
- 読み手が慣れているパターンと一貫性のあるレイアウトを使う
- 重要度順で並んでいる
- 似ているコードは似ているように見せる
- 改行位置やネスト(現在はフォーマッターが主流)
- 関連するコードをまとめてブロックにする
- 似ている考えをグループ分けしてまとめる

11. コメント1
- コメントの目的
- 書き手の意図を読み手に知らせる
- コードを書いている本人は、頭の中に大切な情報があるが、読み手はその情報が失われてし
まう
- コメントすべきで「ない」こと
- 価値のないコメントは記入しない
- 価値のないコメントとは
- コードからすぐにわかることはコメントに書かない
- getHeight() // 高さの取得
- コード以外の「新しい情報」を提供しているか
- 背景や経緯
- コメントのためのコメントはしない
- コードがおかしい可能性、ひどいコードにはコメントではなく名前を変えるべき
- コード自体が読みやすいことが大前提

12. コメント2
- 自分の考えを記録する
- 優れたコメントとは「考えを記録する」ためのものである
- コードは絶えず進化しているので、その過程での欠陥を文章化すべき
- TODOやFIXMEなどのアノテーションを活用(影響範囲が大きい時など)
- 基本その場で改善できるところは改善する(ボーイスカウトの原則)
- 定数には背景となるコメントを残す
- 定数の定義は、その定数が何をするのか、なぜその値を持っているのかという「背景」
が存在する場合が多い
- 読み手の立場になって考える
- 質問されそうなことを想像する
- 関数の内部にロジック分けしたブロック毎へ「要約」したコメントをする
- コメントは正確で簡潔に
- 「これ」「それ」絶対NG
- 短く単純で直感的な言い回し

13. 全体まとめ
・重要度は命名、美しさ、コメントの順
・そもそもコードが読めないのであればコードが悪い、コメントはあくまで補足
・可読性が誰に向けてのものなのかで変わるが、ここでは言語が読めて実装でき
る人へ対してとする(例：JS/TS/Vueの案件では最低限これらを理解していること)
・リーダブルコードで一貫して言われていることは「第三者が自分のコードを
読んで、理解する時間を最短にすること。それが「優れた」コードであ
る」

14. リーダブルコードで一貫して伝えていること
第三者が自分のコードを読んで、理解する時間を最短にすること
それが「優れた」コードである