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

概要

• ペーペーエンジニアの覚書
• リーダブルコードのPrat1をまとめる

リーダブルコードで一貫して伝えていること

第三者が自分のコードを読んで、理解する時間を最短にすること
それが「優れた」コードである

なぜ可読性が必要なのか？

動かすのはPCだが、「読むのは人間」であり、
プログラミングのほとんどの時間はコード読む時間であるため

可読性が低いと何が起きるのか？

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

そもそも読みやすいとは？

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

リーダブルコードで書かれている改善策

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

今回取り上げる改善策 PART1

• 適切な名前
• 目に優しい美しさ
• コメントすべきこと/すべきで「ない」こと

適切な名前（命名）

• 明確で正確な単語を選ぶ

getSize()    // どこのサイズを指しているか曖昧なためNG
getHeight()  // 明確で正確なためOK

• get/fetch/download 状況によって適切で明確なものを選ぶ
• 汎用的な名前は避ける

retval      // NG 
sumSquares  // OK

// ただし、情報の一時的な保管で生存期間が短いケースでは汎用的な名前が役に立つこともある(ループイテレータなど)

• 抽象的な名前よりも具体的な名前を使う(例：値の単位など)

delay    // 何の単位か明確でないためNG
delayMs  // 単位があり明確なためOK

• 重要な属性を追加する

password              // 重要な属性が抜けているためNG
plaintextPassword     // 属性が明確なためOK

 comment              // 重要な属性が抜けているためNG
 unescapedComment     // 属性が明確なためOK

// 全てに属性を追加するのではなく、「バグ」の元になりそうな所へ追加する

適切な名前（誤解されない名前）

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

美しさ

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

コメント1

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

コメント2

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

まとめ

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