software-design-philosophy

ソフトウェア設計の哲学

Ousterhout の A Philosophy of Software Design 第 2 版を使い、ソフトウェアの理解と変更にかかるコストを下げます。Brooks の 概念的整合性がもう一つの軸です。名前を付けた設計または修正、その理由、次のアクションを示します。

ルートを選ぶ

作業	読み込む手法
新しいモジュール、または影響の大きい API／インターフェースの形	references/design-mode.md
既存のコードを変更しながら複雑さを減らす	references/improve-mode.md
差分、設計、PR、または design-gate の入力を評価する	references/review-mode.md

境界に関する判断を伴わない、局所的な命名や構造の整理には clean-code を、テストファーストでの実行には tdd を使います。そのスキルを通じて依頼された作業を続けてください。適切な手法の選択は、新たな承認ゲートではありません。

共通の設計ルール

実際の設計判断を説明する際は、次のキーワードを使います。

• 戦略的 — 次の変更をより安価にするため、今少し設計に投資します。反対は場当たり的（「とにかく動かす」）で、場当たり的な竜巻とは、後始末を残して最速で出荷する人のことです。
• 深いモジュール — 多くの機能を隠し、シンプルなインターフェースを持つモジュールです。コストはインターフェースで、利点はそのインターフェースが隠すものです。浅いモジュールは、インライン化したコードとほぼ同じだけ学習コストがかかります。
• 情報漏洩 — 1つの設計判断が2つ以上のモジュールに反映されている状態です。これは変更の責任範囲の失敗です。その判断の所有者を1つにします。
• 2通りで設計する — 影響の大きい未解決のインターフェースについては、コーディングの前に、実質的に異なる形を2つか3つ比較します。新たな根拠が確立済みのインターフェースに異議を唱えない限り、それを再利用します。
• 戦略的であり続ける — 既存のコードを変更するとき、設計を悪化させる特殊ケースを付け足してはいけません。変更を既存の設計に適合させるか、設計を改善します。
• 重要な点を見極める — この状況が依存する少数の要素を挙げ、その集合を最小化し、それらだけを強調します。
• 書き手ではなく読み手 — 複雑さは、次にコードを変更する人を基準に判断します。自分にとってだけシンプルなら、それは複雑です。
• 概念的整合性／最小限で一貫した形 — 1つのモデルを、問題に必要な大きさを超えないようにします。

例文："これは場当たり的で、浅いモジュールに特殊ケースを加えています。2通りで設計することで概念的整合性を保てます。今1時間余計にかけるコストと、後の情報漏洩を比べてください。"

公式の抜粋からの、もう1つの例文："backspace(cursor) は誤った抽象化です。UI は依然として、どの文字が消えるかを把握する必要があります。delete(start, end) という1つのメソッドにはてこが利きますが、特殊なメソッドにはそれがありません。"

根拠と権限

抽象化、非形式的なインターフェース（呼び出し側が知る必要のあるすべて）、および関連する危険信号や原則を特定できるだけのライブコードまたは提示された設計を調べます。判断を変える可能性がある場合に限り、さらに読み進めます。リポジトリがない場合は、提示された制約を使い、仮定を明示します。

書き手ではなく読み手の観点で考えます。次の開発者は、インターフェースにない事実を知る必要があるでしょうか。そうした事実は、情報漏洩または不明瞭さの証拠です。確立済みの選択を再利用します。代替案を検討するのは、影響の大きい未解決の設計判断に限り、あらゆる局所的な編集で検討するものではありません。

review とすべての design-gate の呼び出しは読み取り専用です。指摘のみを行い、編集やテスト実行はしません。design と improve では、ユーザーの依頼の範囲内で編集できます。無関係なリファクタリングを許可するものではありません。

インタビューでは、境界に関する判断、根拠、制約、参照元を既存の決定記録に記録します。コードの編集、インターフェースのコメント、テストの仕組み、単独のレポートは、後続の承認された段階で扱います。

受け入れ条件

選択したモードの出力フィールドを使用してください。指摘ごとに、その根拠となる公式のレッドフラッグまたは原則を示してください。実際に却下した代替案を報告するか、新たな設計上の選択は不要だったと明記してください。編集を行った場合は、変更したファイル、動作を維持する作業または具体的な動作変更、および実行したチェックや実行できなかったチェックを特定してください。

design-gate では、呼び出し元の正式なゲート結果を使用し、概念的な整合性に関する結論を review_focus に記載してください。判断が漏れている場合、表面的な新しい公開インターフェース、または場当たり的な特例は、設計の根幹に関わるならブロックの理由になり得ます。見た目だけの命名は参考意見にとどめてください。

注意事項

1. 1 行のバグ修正を設計演習に変えないでください。重要度に見合った労力にしてください。
2. 壊れたモデルそのものが依頼の対象なら、既存のパターンを維持しないでください。
3. 一貫性と概念的整合性を混同しないでください。誤りを一貫して繰り返しても、欠陥であることに変わりはありません。
4. カテゴリーを埋めるために指摘を捏造しないでください。clean も有効です。
5. このスキルが要約している書籍の原文を引用したり、再構成したりしないでください。
6. 長さより深さを優先してください（第 9.8 章）。数十行を超えた後では、関数を短くしてもシステムの改善にはほとんどつながりません。小さな関数を増やすと、インターフェースが増え、メソッドが結合します。価値あるコメントを 10 語のメソッド名に置き換えないでください。単一の形式が漏れ出ている小さなクラスは、多くの場合クラスが多すぎます。統合してください。
7. 設計上の判断をコミットメッセージに隠さないでください。コメントはコードに記載してください。
8. private に getter を加えても、情報隠蔽にはなりません。呼び出し側がそのフィールドの存在を知る必要があるなら、それはインターフェースの一部です。
9. 大量のドキュメントは長所ではなく、説明しにくいというレッドフラッグであることがよくあります。設計をシンプルにしてください。

章の参照

選択したモードから、必要な原則、レッドフラッグ、手法にリンクできます。それらの経路に当てはまらない質問の参照先を探す場合に限り、references/chapter-map.md を読み込んでください。