型ヒント形骸化アンチパターン集
🧭 はじめに（What / Why）
このページで理解できることは次の3点です。
- 型ヒントは「書いた瞬間」に価値が生まれるのではなく、運用と文脈で初めて意味を持つこと
- 型ヒントが形骸化すると、安全性ではなく複雑性だけが増えること
- 問題は型ヒントそのものではなく、置き場所と期待のズレであること
型ヒントは設計判断を楽にするための道具であり、目的ではない。
🧱 ① 典型症状
症状1：Any地獄
- 関数・クラス・戻り値が
Anyだらけ - 「とりあえず型を付けた」痕跡だけが残る
- 静的解析は通るが、何も保証していない
症状2：型のための型
- 実体のない
TypeA,TypeB,TypeCが乱立 - 実装より型定義の方が長い
- 変更時に型修正が最大のボトルネックになる
症状3：Union過多・Optional乱用
Union[str, int, None, Foo, Bar]のような型- 呼び出し側が毎回
if分岐を強いられる - 「何が来るか分からない」が型に刻まれている
型が読みにくいコードは、実装以上に設計が壊れている可能性が高い。
🧨 ② 何が問題か
保守性の低下
- 修正のたびに型定義が壊れる
- 型エラー修正が「儀式」になる
- 実装より型合わせに時間を使う
デバッグ性の悪化
- 実行時エラーは依然として起きる
- しかし型があるため「安全だと思い込む」
- バグの発見が遅れる
チーム理解コストの増大
- 型が設計意図を表していない
- 新規参加者が「読めば分かる」状態にならない
- 型注釈がノイズになる
形骸化した型ヒントは「安全だという錯覚」を生み、実害の方が大きい。
🧠 ③ なぜ起きるか
Python文化的背景
- 型ヒントは後付けで導入された
- 「なくても動く」ため、緊張感が生まれにくい
OSS誤用
- mypy / pyright を「怒られないため」に使う
- CIを通すことが目的化する
他言語からの持ち込み
- Java / TypeScript 的な「全部型で縛る」発想
- Pythonの実行時モデルと噛み合わない
Pythonの型ヒントはコンパイル安全性の代替ではない。設計補助輪である。
🛠 ④ 回避策
回避策1：境界にだけ型を集中させる
- 外部入力
- APIインターフェース
- 重要な戻り値
境界で型が堅いと、内部は驚くほど自由になる。
回避策2：Anyは「敗北宣言」として使う
- 本当に分からない場所だけに限定
- コメントで理由を書く
- 後で潰す前提で置く
回避策3：型より不変条件を優先する
- 「Noneでない」より「必ず存在する」
- 「Union」より「別クラス」
- 型で表せない制約は設計で解決する
回避策4：型を削る勇気を持つ
- 読みにくい型は削除候補
- 型を消して可読性が上がるなら、それが正解の場合もある
🧾 ⑤ 教訓（1行で言うと）
型ヒントは「増やすほど安全になる」のではなく、置き場所を間違えた瞬間に負債になる。
このアンチパターン集は、他章（pydantic / dataclass / FastAPI）を読み返すたびに参照すると、判断軸のズレに気づきやすくなる。