「良いコード、悪いコード 」& 「リーダブルコード」の個人的まとめ

概要

以下の書籍に記載されているもののうち、個人的に特に気をつけているコーディングルール（実装時、レビュー時）をまとめました。

• リーダブルコード　
• 良いコード/悪いコードで学ぶ設計入門 ―保守しやすい 成長し続けるコードの書き方

目次

• 目的
• 前提
• コーディングルール

目的

• 書籍で学んだルールの中で自分が開発しているプロダクトに合わせて解釈、取捨選択したものを言語化することによって理解を深める
• まとめたルールを公開することで同じような技術スタック、コーディングスタイルの方の一助になればと

前提

私は業務ではTypescriptでフロントエンドはReact、バックエンドはNode.jsを使用しています。
クラスを用いたオブジェクト指向な書き方ではなく、関数型プログラミングライクな書き方をしています。
そのため、上記書籍のうち、クラス特有のルールについては割愛しています。

コーディングルール

• 変数

  • デフォルトはイミュータブルにする
    • 理由
      • ミュータブルだとコードの処理中に変数の中身が変化してしまう可能性があり、可読性が低下、バグを起こしやすくなるため
    • ミュータブルを許容するケース
      • パフォーマンスに影響するケース
        • 大量のデータの高速処理、画像処理、リソース制約がある組み込みソフトウェアなど
        • 不変にすると値の変更のたびにインスタンスを新しく生成する必要があるため
      • スコープが局所的なケース
        • ループカウンタなど、あるスコープでしか使われないことが確実な変数の場合
  • 変数名に単位情報を記載する
    • 理由
      • ms, Wなど単位がないと変換ミスが起きやすい

• メソッド

  • フラグ引数は使わない
    • 理由
      • フラグによってどのような処理分岐になっているか、関数内を読み解かなければいけないため
    • フラグ引数を使いたくなった場合には、メソッドを分ける、もしくは呼び出し側でフラグの処理分岐を行う

• コメント

  • ロジックの内容をなぞるだけのコメントをしない
  • 可読性の悪いコードをコメントで補足しない。代わりにコードの可読性をあげる

• その他

  • マジックナンバーはロジックにベタ書きせず変数に格納して定義する

    • 理由
      • 仕様変更の際に一度に該当箇所を漏れなく変更できる
      • 変数名でマジックナンバーが何を表す数字なのか読み手が理解できる

  • 一見同じコードでも概念が異なれば別々に実装する

    • 理由
      • 違う概念だが、一見同じようなコードなため、共通化すると、共通化コードに一方の都合で修正を行った場合に他方で予期せぬ影響が出てしまう
      • ex) typecriptでPrice(価格)とDistance(距離)の型定義をする場面で、どちらもnumber | nullだったとしても共通化せずに別々の型として実装する

  • テスト関数には説明的な名前を付けてどんな条件をテストしているのかわかるようにする

    • 理由
      • 説明的でないと第三者が見たときにコードを読み解かないとテスト内容が理解できないため
      • 主なテストツールはテストが失敗した際に関数名が表示されるため、デバックに役立つ

  • if文内では早期return、ループ内では早期continueできないか検討する

    • 理由
      • ネストを浅くできるため