code-style-typescript

TypeScript コードスタイルガイド

適用する場合

• 新しい TypeScript コードを記述するとき
• .ts ファイルのコードレビュー時
• 既存のコードをリファクタリングするとき
• TypeScript のコードスニペット、例、ドキュメントを生成するとき
• Markdown、Vue.js などに含まれる TypeScript 関連のブロックを扱うとき
• コードをフォーマットまたは整理するとき

ルール

すべてのルールのコード例は、references/examples.md にあります。

ルール：文末にセミコロンを付けない

文末にセミコロンを付けないでください。

例外：TypeScript のインターフェース、型、および同様の型定義では、プロパティの区切りにセミコロンを必ず使用してください。

// Statements - no semicolons
const result = calculateValue()

// Interfaces - semicolons required
interface User {
  id: number;
}

type Config = {
  timeout: number;
}

詳しくは、例 → セミコロンを付けないを参照してください。

ルール：条件文内でメソッドを呼び出さない

条件文（if、while、for など）で使用する前に、メソッド呼び出しを別の変数に抽出してください。

例 → メソッド呼び出しをしないを参照してください。

ルール：型付きコードでは明示的な存在チェックを使用する

型付きの値が存在するかどうかを確認するときは、value === undefined、value !== undefined、value === null、value === '' のような明示的な比較を使用してください。

通常のアプリケーションコードで存在を確認する際、truthy/falsy による型の絞り込みに頼らないでください。

例 → 明示的な存在チェックを参照してください。

ルール：関数呼び出しを引数にしない

他の関数の引数として使用する前に、関数呼び出しを別の変数に抽出してください。

例外：バリデータースキーマ、DSL 設定、クエリビルダー、マッチャー API など、読みやすさのためにネストした呼び出しが必要なまれなケースでは、複数行に分けて記述してください。例 → ネストした関数呼び出しを参照してください。

例 → 関数呼び出しを引数にしないを参照してください。

ルール：1 行の宣言はまとめ、複数行の宣言は分ける

1 行の const および let 宣言は、空行を挟まずにまとめてください。1 行の宣言から複数行の宣言に移るとき、または複数行の宣言同士を分けるときは、空行を入れてください。

例 → 1 行の宣言をまとめるを参照してください。

ルール：ローカル名に分かりにくい略語を使わない

分かりやすいローカル変数名を使用してください。完全な単語が短く、より明確な場合は、pv、prop、cat、cfg のような分かりにくい略語を避けてください。

id、db、URL、HTML など、広く知られた技術的な識別子は使用できます。

例 → 分かりやすいローカル名を参照してください。

ルール：JSDoc コメントは 1 行で記述する

1 行の JSDoc コメントは、/** と */ を含めて同じ行に記述してください。

例 → JSDoc コメントを 1 行で記述するを参照してください。

ルール：オブジェクトのキーの順序

省略形のプロパティを先に記述し、次に通常のプロパティを記述してください。どちらのグループもアルファベット順に並べてください。

const config = {
  isActive,
  timeout,
  apiKey: 'secret-key',
  baseUrl: 'https://api.example.com'
}

例の全容については、例 → オブジェクトのキーの順序を参照してください。

ルール：複数の値を持つオブジェクトと配列のリテラルを展開する

キーが 1 つのオブジェクトと要素が 1 つの配列は 1 行のままでもかまいません。キーが 2 つ以上のオブジェクトと要素が 2 つ以上の配列は、1 行に 1 つずつ記述してください。

例 → 複数の値を持つリテラルを展開するを参照してください。

ルール：複数行のオブジェクト値は空行で区切る

オブジェクト内の複数行の値は、空行で区切ってください。

例 → 複数行のオブジェクト値を区切るを参照してください。

ルール：末尾のカンマを付けない

配列、オブジェクト、その他の構造で末尾のカンマを使用しないでください。

例 → 末尾のカンマを付けないを参照してください。

ルール：return の前に派生データを計算する

ハンドラーまたは関数で派生データが必要な場合は、先に別の変数に計算しておき、最後の return はシンプルで明示的なものにします。

明示的なオブジェクトのほうがわかりやすい場合は、フィールドを置き換えるためだけに ...spread でオブジェクトを作り直すのは避けます。

例 → return の前に派生データを計算するを参照してください。

ルール：複数行ブロックと末尾の return は空行で区切る

複数行ブロック（if/else、ループ、try/catch、関数など）は、親ブロックの先頭または末尾にある場合を除き、他のコードと空行で区切ります。同じブロック内に先行する文がある場合は、return の前にも同様に空行を入れます。

例 → 複数行ブロックを区切るを参照してください。

ルール：フラットなインターフェース構造

すべての interface（および名前付き type エイリアス）では、名前付きプロパティを1階層のみにします。プロパティの型がオブジェクトの形状を表す場合は、独立した名前付きインターフェースとして定義します。

// ✅ Correct - extracted interfaces
interface Brand {
  name: string;
  slug: string;
}

interface Item {
  brand: Brand;
  id: string;
  name: string;
}

// ❌ Wrong - nested object shapes inline
interface Item {
  id: string;
  brand: { name: string; slug: string; };
  name: string;
}

深くネストされた例については、例 → フラットなインターフェース構造を参照してください。