simplify

コードの簡素化

概要

動作を完全に維持しながら、複雑さを減らしてコードを簡素化します。目的は行数を減らすことではありません。読みやすく、理解しやすく、変更しやすく、デバッグしやすいコードにすることです。簡素化のたびに、次の簡単な基準で判断してください。「新しいチームメンバーは、元のコードよりも早く理解できるだろうか？」

使用するタイミング

• 機能が動作し、テストも通っているものの、実装が必要以上に重く感じられるとき
• コードレビューで読みやすさや複雑さの問題が指摘されたとき
• 深くネストしたロジック、長い関数、分かりにくい名前に遭遇したとき
• 時間に追われて書いたコードをリファクタリングするとき
• 複数のファイルに散在する関連ロジックを集約するとき
• 重複や一貫性のなさを生む変更をマージしたあと

使用しないタイミング：

• コードがすでに整理されていて読みやすいとき。むやみに簡素化しないでください
• コードの動作をまだ理解していないとき。簡素化する前に理解してください
• パフォーマンスが重要なコードで、「より単純な」バージョンのほうが測定可能なほど遅くなるとき
• モジュール全体を書き換える直前のとき。使い捨てのコードを簡素化しても労力が無駄になります

5 つの原則

1. 動作を完全に維持する

コードの動作は変えず、表現方法だけを変えてください。すべての入力、出力、副作用、エラーの動作、エッジケースを同一に保つ必要があります。簡素化によって動作が維持されるか確信が持てない場合は、変更しないでください。

変更するたびに、次の点を確認してください。

• すべての入力に対して同じ出力になりますか？
• エラーの動作は同じですか？
• 副作用とその順序は維持されていますか？
• 動作の変化を明らかにするには、どの程度の最終状態の検証が適切ですか？

2. プロジェクトの規約に従う

簡素化とは、外部の好みを押し付けることではなく、コードベース内の一貫性を高めることです。

簡素化する前に、次のことを行ってください。

1. AGENTS.md とプロジェクトの規約を確認する
2. 近接するコードが類似のパターンをどのように扱っているか調べる
3. インポート、命名、関数の書き方、エラー処理、型注釈に関するプロジェクトのスタイルに合わせる

プロジェクトの一貫性を損なう簡素化は、簡素化ではなく、無用な変更です。

3. 巧妙さより明快さを優先する

簡潔なコードを解釈するために一瞬でも考える必要があるなら、明示的なコードのほうが優れています。

• ネストした三項演算子を、読みやすい制御フローに置き換える
• 密なインライン変換で意図が分かりにくくなる場合は、名前付きの中間ステップに置き換える
• 数行増えても、役に立つ名前は維持する

4. バランスを保つ

過度な簡素化に注意してください。

• 意味を担う名前をインライン化して消さない
• 関係のないロジックを、より大きな 1 つの関数にまとめない
• テスト容易性や拡張性に役立つ抽象化を削除しない
• 理解しやすさより行数の少なさを優先しない

5. 変更箇所に範囲を限定する

基本的には、最近変更したコードを簡素化してください。明示的に依頼されていない限り、無関係な箇所のついでのリファクタリングは避けてください。

手順

ステップ 1：変更する前に理解する

何かを変更または削除する前に、それが存在する理由を理解してください。

次の点を確認してください。

• このコードの責務は何ですか？
• 何から呼び出され、何を呼び出していますか？
• エッジケースとエラー経路にはどのようなものがありますか？
• 期待される動作を定義するテストはありますか？
• なぜこのように書かれている可能性がありますか？

答えられない場合は、まずさらにコンテキストを確認してください。

ステップ 2：簡素化できる箇所を探す

判断の手掛かり：

• 深いネスト
• 異なる責務が混在する長い関数
• ネストした三項演算子
• ブール値フラグ引数
• 繰り返される条件判定
• 汎用的すぎる名前、または誤解を招く名前
• 重複したロジック
• デッドコード
• 価値を加えないラッパーや抽象化

ステップ 3：段階的に変更を適用する

簡素化は一度に 1 つずつ行ってください。

それぞれの簡素化について、次の手順に従ってください。

1. 変更を行う
2. 適切な最終状態の検証計画を使って、動作が維持されていることを確認する
3. 証拠から動作の維持が確認できる場合に限り、変更を残す

可能な限り、リファクタリングと機能開発は分けてください。

ステップ 4：結果を確認する

簡素化した後、次の点を確認します。

• コードが実際に理解しやすくなっている
• 差分が明確でレビューしやすい
• プロジェクトの規約に引き続き準拠している
• 動作、エラー処理、副作用が変わっていない

このリポジトリでのガイダンス

• 巧妙に短くまとめるより、分かりやすい TypeScript を優先します
• 既存の実行時の動作、テスト、フックを維持します
• 可読性の向上につながる場合は、明示的な名前と、責務を絞った小さなヘルパーを優先します
• リファクタリングの範囲は、タスクまたはレビューのフィードバックに密接に関連する部分に限定します

最終状態の確認

最終差分に対して、適切な範囲の最終状態確認計画を使用します。リポジトリおよびリリースの手順で必須とされるチェックを実行し、変更範囲や明示された不確実性に応じてのみ、証拠を追加または再確認します。