coding-standards

コーディング規約

D9 の正規リファレンス。 これは、言語横断的なコーディング規約の唯一の信頼できる情報源です。 言語固有のレビュアー（@typescript-reviewer、@python-reviewer など）には、これらのルールが組み込まれています。 エージェントはこのスキルを「関連項目：/coding-standards」として参照します。

命名規則

変数と関数

言語	変数	関数	定数
TypeScript / JavaScript	camelCase	camelCase	SCREAMING_SNAKE_CASE
Python	snake_case	snake_case	SCREAMING_SNAKE_CASE
Go	camelCase	camelCase	CamelCase（エクスポート対象）
Rust	snake_case	snake_case	SCREAMING_SNAKE_CASE
Java	camelCase	camelCase	SCREAMING_SNAKE_CASE
C#	camelCase	PascalCase	PascalCase
Swift	camelCase	camelCase	camelCase

クラス／型／インターフェース

すべての言語で PascalCase を使用します。例外はありません。

真偽値

is、has、can、should を先頭に付けます：isLoading、hasError、canEdit、shouldRefresh。

コレクション

複数形の名詞を使用します：users、errors、items。userList、errorArray は避けます。

避けるもの

• ループカウンター以外での1文字変数（ループ内の i、j、k は可）
• 3文字未満しか短縮できない略語：usr → user、mgr → manager
• 冗長な型名：UserInterface、UserClass、UserObject ではなく、単に User

---

関数設計

• 最大行数： 50 行（明確な目安。80 行を超える場合は必ず分割を検討します）
• 単一責任： 1つの関数につき1つの役割です。説明に「そして」が含まれる場合は分割します
• 最大引数数： 3。これを超える場合はオプション／設定オブジェクトを使用します
• 循環的複雑度： ≤ 10。> 15 の場合は必ずリファクタリングします
• ネストの深さ： ≤ 3 レベル。早期リターンを使用して浅くします

早期リターンのパターン（推奨）

// BEFORE — deep nesting
function handle(input) {
  if (input) {
    if (input.valid) {
      return process(input);
    }
  }
  return null;
}

// AFTER — early returns
function handle(input) {
  if (!input || !input.valid) return null;
  return process(input);
}

---

エラー処理

• エラーを黙って握りつぶさない： catch (e) {} は常に誤りです
• エラーメッセージにはコンテキストを含める： "Error" ではなく "Failed to fetch user id=42"
• 伝播するか処理する： 適切なレベルでエラーを処理するか、再スローします。両方行うことも、どちらも行わないことも禁止です
• 型付きエラー（TypeScript）： 汎用的な new Error ではなく、class NotFoundError extends Error { constructor(id: string) ... }
• Python の例外： 特定の例外型を捕捉します。裸の except: は禁止です
• Go のエラー： 返されたエラーは必ず確認します。比較には errors.Is()／errors.As() を使用します
• Rust の結果： 伝播には ? を使用します。ライブラリコードで .unwrap() は使用しません

---

コード構成

不変性を優先

• let より const（JS/TS）、var より val（Swift/Kotlin）、適切な場合は final を使用します
• 構築後に再代入しないフィールドには readonly を指定します
• 関数の引数には不変データ構造を優先します

マジックナンバーを使わない

// BAD
if (retries > 3) { ... }
setTimeout(fn, 5000);

// GOOD
const MAX_RETRIES = 3;
const POLL_INTERVAL_MS = 5000;
if (retries > MAX_RETRIES) { ... }
setTimeout(fn, POLL_INTERVAL_MS);

コメントアウトしたコードを残さない

不要になったコードは削除します（Git の履歴に残ります）。 近いうちに必要になるコードはブランチに置きます。 自明でない判断の説明に必要な場合は、コメントアウトしたコードではなくコメントとして残します。

---

アンチパターンのリファレンス

パターン	重大度	理由
可変なグローバル状態	HIGH	予測不能な副作用を招き、依存関係が見えにくくなります
await されていない Promise	HIGH	未処理の非同期エラーが黙って握りつぶされます
TypeScript での any	MEDIUM	呼び出し境界を越えて型安全性が損なわれます
本番コードでの console.log	LOW	ログが過剰になり、機密性の高い状況ではデータ漏えいにつながる可能性があります
課題管理ツールへの参照がない TODO	LOW	恒久的な技術的負債になります
ゴッドオブジェクト	HIGH	1つのクラスに責務が多すぎます
インラインのマジックナンバー	MEDIUM	意図が不明瞭になり、保守上のリスクになります
コピー＆ペーストしたロジック	MEDIUM	時間とともに気づかれないまま差異が生じます
コンテキストを付けずに捕捉して再スローする	MEDIUM	スタックトレースの意味が失われます
ネストした三項演算子	MEDIUM	読みにくくなります。代わりに if/else または switch を使用します

---

SOLID 原則のチェックリスト

• Single Responsibility（単一責任）：このクラス／関数は、厳密に1つのことだけを行っていますか？
• Open/Closed（オープン／クローズド）：継承による変更ではなく、コンポジション／インターフェースを通じて拡張していますか？
• Liskov Substitution（リスコフの置換原則）：呼び出し側に問題を起こすことなく、サブタイプで常に基底型を置き換えられますか？
• Interface Segregation（インターフェース分離）：肥大化したインターフェースはありませんか？クライアントは使用しないメソッドに依存していませんか？
• Dependency Inversion（依存関係逆転）：具体的な実装ではなく、抽象（インターフェース）に依存していますか？

---

関連項目

• @code-reviewer — コードレビュー中にこれらのルールを適用します
• @typescript-reviewer、@python-reviewer など — これらを基準とする言語固有のルール
• @security-reviewer — セキュリティ固有の標準（OWASP、シークレット、暗号化）