code-maintainability

コードの保守性

コードの作成、リファクタリング、または変更されたコードのレビューを行う際は、コードの読みやすさを保ち、変更にかかるコストを抑えるために、常にこの機能を使用してください。以下の各項目は、それぞれ 2 つのモードを持つ観点です。コードを作成する際に守るべき実践と、変更をレビューする際に指摘すべき問題です。どちらのモードでも同じ基準を適用してください。自分で書いたコードだからといって、基準を緩めてはいけません。

プロジェクトの開発規約や構造規約、またはプロジェクトで定義されたコンポーネント、ルーティング、ドメインのスキルがルールを担当している場合、この機能は保守性の観点を適用し、内容を重ねて説明するのではなく、担当する規約を名前で示して委ねます。「プロジェクトにそのような規約がある場合」という条件が付いたルールは条件付きです。その規約がないプロジェクトでは、適用せずに問題なく読み飛ばしてください。

ガイドライン：

• ルールを担当するスキルがある場合は、プロジェクトの開発、構造、コンポーネント、ルーティング、またはドメインの規約のうち該当するものに、名前を挙げて必ず委ねてください。内容の重複は避け、要約してください。
• プロジェクト固有の規約が条件となる項目は、その規約がないプロジェクトでは違反ではなく、適用対象外として扱ってください。

この文書における「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 に記載された意味で解釈してください。

命名と構成

命名と構成では、以下について説明しています。

• ファイル名をプロジェクトで定められた命名規約（例：ケバブケース）に従わせること、およびその規約で必要となる同じ場所に置く関連ファイル（対になるスタイルモジュールファイルなど）について
• コンポーネント、ヘルパー、データアクセスモジュールを適切なディレクトリ階層（ルート固有、グループ共有、グローバルの順）に配置すること、および階層を選ぶためのフローチャートについて
• プロジェクト独自のルーティング規約が定義されている場合はそれに従うこと、およびルートに必要な関連ファイル（props/types、not-found、social-image）を同じ場所に置くこと
• 識別子の名前と大文字・小文字の使い方を、変更対象のファイルおよびその周辺の規約に合わせること
• ほかの規則で定められていない名前に適用する識別子の基本語彙、およびプロジェクト規約、担当する機能、または値が渡されるプラットフォーム／ホスト API にどのように従うか
• プロジェクト規約が確立されていても、分野固有の意味が曖昧な識別子を命名すること。これには、文書化されたプロジェクトの機能における、最も近い形で組み合わせる命名原則、その局所性に関する例外、およびその機能がない場合にも適用される内容を含みます

抽象化の境界

抽象化の境界では、以下について説明しています。

• 1 つの関数、クラス、またはモジュールに何を含めるべきかを決定またはレビューする方法、および凝集性の尺度が線形ではない理由。機能的凝集性はほかの種類よりはるかに強く、偶発的凝集性と論理的凝集性は中間の段階よりはるかに弱いこと
• 新たな共有ロジックを、複数の呼び出し元がある最も低い階層（グループ共有、グローバルよりもルート固有を優先）に配置すること
• プロジェクト独自のコンポーネント規約が定義されている場合、それに従ってサーバー／クライアントの境界を分けること
• プロジェクト独自のドメイン規約が定義されている場合、それに従い、コンテンツのレンダリングチェーンなどのドメイン固有のパイプラインを、担当する単一のモジュール内に保持すること
• 階層間のインポートを適切な方向に保ち、共有コードがルート固有のコードに依存しないようにすること

複雑さと読みやすさ

complexity-and-readability.md では、次の内容を説明しています。

• プロジェクトで設定されたリンターの基準や、複雑さ・長さの上限を守ること。上限を超える関数の評価も含みます。
• マジックナンバーやマジック文字列には名前付き定数またはデザイントークンを割り当て、正当な理由があるまれなケースに限り、理由をコメントで示したインラインのリンター抑制ディレクティブを使うこと。
• 一見不要なコード（未使用のインポート、到達不能な分岐、コメントアウトされたブロック）を削除するか残すかを判断すること。
• 説明コメントもドキュメントコメントも最後の手段であり、最初から頼るものではない理由――最善の記述にはどちらも必要ありません――エクスポートされた名前や一連のエクスポートが不明瞭なために必要となるドキュメントコメントは、ドキュメント作成の課題ではなく境界の欠陥である理由、そして単位、null 許容性、境界値を含むかどうかは、どちらのコメントよりも先に型または名前で示すべき理由。
• コメントを許容する前に試すべき、順序付けられた対処法――名前と型、次にインターフェース、さらに単位の分割方法――および、型でも名前でも取り除けないコメントを受け入れる前に、abstraction-boundaries.md の凝集性に関する判断を参考に、その分割を再検討すること。
• 実装の詳細を説明しなければならない境界のドキュメントコメントは、十分に文書化されたインターフェースではなく、浅いインターフェースを示す理由。
• ドキュメントコメント、内容を言い換えるコメント、コメントの文体に関するルールはプロジェクトの開発規約に委ねること。また、静的型付け言語では、繰り返し使われるインライン型を名前付きエイリアスとして切り出すこと。

スコープの規律

scope-discipline.md では、次の内容を説明しています。

• 変更内容を明示された目的に一致させること。目的に明記されていないファイルの評価も含みます。プロジェクトの開発規約に従い、ついでのリファクタリングは行いません。
• 既存の問題はこの変更に含めず、別途指摘すること。
• 新しいヘルパー、プロパティ、設定オプション、ジェネリック型パラメーターが、推測に基づくスコープ拡大になっていないか評価すること。
• 新しい抽象化は具体的な呼び出し箇所が2つ以上ある場合に正当化すること（YAGNI）。繰り返しのロジックを切り出したり統合したりするのは、本当に同じ関心事である場合に限ります（無関係な呼び出し元を結合させずに DRY を実現します）。