clean-typescript

クリーンな TypeScript

私たちは、TypeScript を形式的な手続きではなく、正確性と明瞭さを高めるためのツールとして使用します。 型によってバグと認知負荷を減らすべきです。

型の考え方

• 推奨：巧妙な型や汎用性が高すぎる型より、明示的で読みやすい型を使います
• 避ける：any と安全でない型アサーション
• 必要な場合は any の代わりに unknown を使います
• 型推論が明確で安定している場合は、TypeScript の型推論に任せます

型とインターフェース

• ほとんどの用途では 推奨：type エイリアスを使います
• interface は主に、公開され、拡張可能なオブジェクトの形状に使用します
• 型は小さく、組み合わせ可能で、適切な名前を付けます

関数と API

• 公開関数では 推奨：戻り値の型を明示します
• API を大きく改善する場合を除き、関数オーバーロードは避けます
• 関数のシグネチャはシンプルで予測しやすいものにします

Null 許容性と安全性

• null と undefined を明示的に処理します
• 使用しない：最後の手段を除き、非 null アサーション（!）に依存しません
• 制御フローとガードによる型の絞り込みを優先します

列挙型と定数

• 避ける：enum
• 推奨：ユニオン型または as const オブジェクト
• 実行時の出力は予測可能かつ最小限に保ちます

エラー処理

• 型エラーとエラー状態を明示的に型付けします
• 適切な場合は、例外のスローより結果オブジェクトまたは型付きエラーを優先します
• 汎用的すぎる型によって失敗の形態を隠さないでください

一般原則

• 型によって意図を説明できるようにします
• 型が理解しにくい場合、その型はおそらく適切ではありません
• 理論上の完全性より保守性を優先します