coding-standards

React/TypeScript基本実装ルール

基本方針

• 早期returnでネストを浅くする
• クラスを使わず type / interface を使用
• 引数が4つ以上または同じ型の引数がある場合はオブジェクトで受け取る
• ESLint/Prettierの標準ルールに準拠
• if文には必ず波括弧 {} を付ける（ワンライナー禁止）
• マジックナンバーは使用せず定数を定義
• 論理演算子（&&, ||）や三項演算子（? :）を2つ以上チェーンしない。複雑な条件は意図を表す名前の関数に切り出す

一般原則

• 単一責任の原則: 関数・モジュールは「1つのこと」に集中
• 不変性を優先: const/readonly、イミュータブルな更新
• 副作用の分離: 純粋関数を基本、I/O・状態変更は境界に寄せる
• 明示的なインターフェース: 公開APIを最小限に
• 命名は意図を表現: 略語・あいまい語を避け、ドメイン語彙を使用

TypeScriptの原則

• any は原則禁止（必要な場合も局所化し unknown からの絞り込み）
• 返り値の型は基本的に明示
• 列挙は union type を優先
• 定数は as const を活用

コメントルール

• docコメント: 関数のdocコメントは必ず記載。パラメータがある場合は @param、例外を投げる場合は @throws、戻り値がある場合は @returns も必須
• 実装の意図: 特別な理由で実装している箇所はコメントを記載
• その他: 上記以外はコメントを記載しない

エラーと入力バリデーション

• 入力境界でバリデーションと正規化を行う
• バリデーション実装はライブラリ非依存とする（zod が無い場合は type guard / schema 関数で対応）
• 例外の握り潰しを避ける
• ユーザー向けメッセージと開発者向けログを分ける

非同期処理

• async/await を優先
• 原則 try/catch は使わない（関数内での乱用を禁止）
• 想定可能な失敗は例外で投げず、戻り値で失敗可能性を表現する（例: Result<T, E> / Either / 判別可能union）
• 例外的に許可: 想定不可能な障害やインフラ例外を I/O境界・外部API境界・ジョブ実行境界など最上位層で集約する場合のみ
• タイムアウト・リトライ・キャンセルのポリシーを決める

React向け補足

• コンポーネントは小さく保ち、可能な限り純粋に
• propsは読み取り専用、内部での再代入を避ける
• useEffect の依存配列は正確に保つ
• メモ化は必要な場合に限定