概要
- ペーペーエンジニアの覚書
- リーダブルコードの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の案件では最低限これらを理解していること)
- リーダブルコードで一貫して言われていることは「第三者が自分のコードを読んで、理解する時間を最短にすること。それが「優れた」コードである」