AI がコードベースに与える変化について、意図的に考慮しましょう。

Summary

テキストは、関数とデータモデルをシンプルかつ明示的に保つことでクリーンでテスト可能なコードを書く方法を説明しています。

Semantic functions（セマンティック関数） は最小限で自己記述的な単位であり、必要な入力をすべて受け取り、副作用が意図されない限り副作用なしにすべての出力を返します。高いユニットテスト性が求められ、コメントは不要です—コード自体が振る舞いを説明するべきです。

Pragmatic functions（プラグマティック関数） は複数のセマンティック関数や独自ロジックをラップして、頻繁に変わる可能性のある複雑なプロセスを整理します。再利用されることはほとんどないため、プラグマティック関数が一般的になる場合は、再びセマンティック単位へ分解すべきです。これらの関数に対するドキュメントコメントは、（例：「balance が10未満の場合に早期失敗」）など予期しない振る舞いを強調し、明白な特性を繰り返さないようにします。

Data models（データモデル） は不可能な状態の組み合わせを防ぐことでデータ正確性を保証する必要があります。オプションフィールドや緩い型付けはエラーリスクを増大させます。モデル名はその目的を正確に示すべきで、開発者が各フィールドを逐一確認せずともフィールドの関連性を推測できるようにします。独立した概念は別々のモデル（例：

UserAndWorkspace { user: User, workspace: Workspace }

）として構成し、フラット化しないでください。また、同じ形状でも異なるドメイン概念を表す場合にはブランド型（例：

DocumentId(UUID)

）を使用して区別します。

セマンティック関数が便利さのためにプラグマティック関数へ変わると、下流コードはその振る舞いを誤解する可能性があります。機能ではなく意図された使い方で関数名を付けることでこれを緩和できます。

モデルは追加のオプションフィールドが新しいモデルを作らずに増えると、疎結合データとなり消費者がフィールドの関連性を推測せざるを得なくなります。フィールドがモデル名や意図された概念と整合しなくなる場合は、モデルを分割すべき明確なサインです。

これらの原則に従うことで、チームは技術的負債を減らし、保守性を向上させ、より信頼性の高いソフトウェアを提供できます。

意味論的関数

任意のコードベースからブロックを構築し、正確性を優先して最小限に保つ。
すべて 必要な入力を受け取り、必要な出力をすべて 直接返す。
他の意味論的関数をラップして望ましいフローを表現できる；複雑な流れが明確に定義されている場合はそれらを使用する。
副作用は、明示的な目的でない限り避ける。こうすれば内部を調べずとも安全に再利用できる。
大きなフローが不明瞭なときは、次のステップが必要とするものだけを渡し、他には何もしない自己記述的意味論的関数の連鎖に分割する。

良い例：

quadratic_formula()

、

retry_with_exponential_backoff_and_run_y_in_between<Y: func, X: Func>(x: X, y: Y)

。

コメントは不要；コード自体が自己記述的であるべき。
単体テストが容易にできるよう設計する。

実用的関数

いくつかの意味論的関数とユニークなロジックをまとめ、複雑なプロセスを表現する。
適度に使用する―多所で出現したら意味論的関数へのリファクタリングを検討。

例：

provision_new_workspace_for_github_repo(repo, user)

、

handle_user_signup_webhook()

。

統合テストでアプリ全体の機能を実行しながらテストする。
頻繁に変更される想定；上部にドキュメントコメントを入れる。
- 関数名や明白な特徴は繰り返さない。
- 想定外の振る舞い（例：
```
balance <10
```
  の場合は早期失敗）を記載する。
- ドキュメントコメントは更新忘れに注意。

モデル

不可能な状態が発生しないようデータ構造を整える。
相互排他的なフィールド組み合わせを許容するモデルは避ける；各オプションフィールドで呼び出し側に毎回質問させる。

正確な名前付け：例

UnverifiedEmail

、

PendingInvite

、

BillingAddress

。

独立した概念を組み合わせ、フラット化は避ける（例：
```
UserAndWorkspace { user: User, workspace: Workspace }
```
）。
原語型にブランド付与して誤交換を防ぐ（例
```
DocumentId(UUID)
```
と単なる
```
UUID
```
を区別）。

問題が起きる場所

意味論的 → 実用的ドリフト：意味論的関数が便利さのために実用的になると、下流コードが誤用しやすくなる。
- 何をするか よりも どこで使われるか に基づいて命名すると、振る舞いが厳密に定義されていないことを示し、回帰デバッグが容易になる。
モデルの低下はゆっくり進む：追加機能のためにオプションフィールドを増やすとモデルの凝集度が薄れる。
- フィールドが名前と合わなくなったら、個別のエンティティへ分割する。

AI がコードベースに与える変化について、意図的に考慮しましょう。

Japanese Translation:

Summary

同じ日のほかのニュース