変更衛生とコードクラフト は何をしますか？
概要
変更の形とコードの記述方法について。2つのテーマ: 構造的変更と振る舞いの変更を分離すること、そして動作する最もシンプルな方法で意図を明確に表現すること。
変更衛生
- 構造的変更は振る舞いの変更より先に、独立して検証する。 再編成（ファイル分割、リネーム、コメント追加）は、振る舞いの変更（新しい制約、ロジックの変更）とは別の、独立してチェック可能なステップとする。両方を1つの不可分な変更に混ぜてはならない。レビュアーは安全な再構成と実際のロジック変更を区別できない。
- 変更は1つの関心事につき1つ。 変更は単一の、説明可能な目的を持つ。
- 作業中のコードを改善する（問題がタスクに影響する場合、キャンプサイトをよりきれいにする）が、無関係なリファクタリングは行わない。目標に集中する。
コードクラフト
- 暗黙的より明示的。 名前があるべき場所にワイルドカードなし、暗黙のキャストなし、空文字列やマジックセンチネルなし。意図を明確に述べる。
- 説明的な名前。 関数・変数はその動作を説明する。言語やエコシステムのイディオムに従う。
- コメントは意図を、仕組みは書かない。 非自明な場合になぜを説明する。自明なコードへのコメントは省略する。
- 小さく、単一目的のユニット。 どのユニットも、内部を読まなくても、何をするか、どう使うか、何に依存するかを説明できるべき。大きなファイルは通常、やりすぎである。
- 本番コードでは判断をもってDRYに。 重複はシグナルであり、自動的なエラーではない。2つ目のほぼ同一の出現が、抽象化するか、その理由を記録するかの意図的な判断を引き起こす。共有された意味を抽象化し、偶然の形は抽象化しない。見た目は似ていても異なる理由で変更されるものは分離する。
- エコシステムの標準に従う。 有能な実践者が期待するイディオムとよくサポートされたライブラリを使用する。プラットフォームが解決したものを再発明しない。
名前付きの緊張関係
- DRY vs. 早期抽象化: 本番コードは、意図の実証された繰り返しに基づいて抽象化する。予期される繰り返しではない。判断に迷ったら、3回目の出現を待つ（YAGNIがタイブレークを支配する）。
- DRY vs. DAMP: 本番コードはDRYに。テストコードはDAMPに（重複排除よりも明確さ、
tests-as-a-control参照）。テストにDRYを適用するのは違反である。
よくある正当化
| 言い訳 | 現実 |
|---|---|
| 「リネームと機能追加を1つのコミットでやります」 | 構造と振る舞いが1つの差分にあるとレビュー不可能。分離せよ。 |
| 「コピーが2つあるから、今すぐDRYにしなければ」 | 2回目の出現 = 判断せよ。同じ形 ≠ 同じ意味。偶然の重複は分離すべき。 |
| 「ついでだから、この別モジュールもリファクタリングしよう」 | 無関係なリファクタリングはスコープとリスクを拡大する。メモしておき、今はやらない。 |
| 「賢いワンライナーのほうがエレガントだ」 | 明示的は賢いより勝る。次の読み手のために最適化せよ。 |
赤旗 — 中止
- コードの移動と振る舞いの変更を同時に行う差分
- 目的を説明するのに「そして」という単語が必要なPR
- 類似性の最初の出現で、または予期される（実際ではない）繰り返しに基づいて抽象化すること
- 頭の中に収まらなくなったファイル
完全な理論的根拠: 憲法の第5条および第6条。engineering-constitution/references/engineering-constitution.md にバンドルされています。