typescript-naming

命名

現在のタスクにおいて、TypeScript スタイルガイドの命名規則を適用します。

ワークフロー

1. 利用するリポジトリの規約と設定を確認します。
2. 明示的なリポジトリの規約がある場合は、この独自の指針より優先します。
3. タスクに関連する指針のみを適用、確認、または説明します。
4. 適切な名前やドキュメントが文脈や判断に左右される場合は、重要なトレードオフを示します。

適用範囲

• ESLint などのツールで自動的に確認できる内容は、それらのツールに任せます。
• このスキルが有効だからといって、無関係な TypeScript スタイルガイドの規約を持ち込まないでください。

関連する指針

Satisfies を使った型安全な定数

既存の型に照らして定数を検証する詳しい指針については、利用可能な場合は typescript-types を使用してください。

命名

自分が書いたコードを別の人が保守することを念頭に、重要な文脈を示しながら、命名規則の一貫性と読みやすさを保つよう努めます。

名前付きエクスポート

<Rule prefix="すべてのインポートで一貫したパターンを確保するため、名前付きエクスポートを使用する必要があります" href="https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-default-export.md"

{export default [ { rules: { 'import/no-default-export': 'error' }, }, // In case of exceptions disable the rule { files: ['src/pages/**/*'], rules: { 'import/no-default-export': 'off' }, }, ]; }

これにより、コードベース全体で変数名や関数名の一貫性を保てます。また、宣言されていないものをインポートしようとするとエラーになるという利点もあります。

命名規則

最適な名前を見つけるのが難しい場合もありますが、以下の規約に従い、一貫性と将来の読み手にとっての分かりやすさを高めることを目指します。

変数 {#variables-1}

• ローカル変数
  キャメルケース
  products、productsFiltered

• ブール値
  is、has などを接頭辞として付けます。
  isDisabled、hasProduct

  {`'@typescript-eslint/naming-convention': [ 'error', { selector: 'variable', types: ['boolean'], format: ['PascalCase'], prefix: ['is', 'are', 'should', 'has', 'can', 'did', 'will'], } ] `}

• 定数
  大文字で始めます。

  const FEATURED_PRODUCT_ID = '8f47d2a1-b13e-4d5a-a7d8-6ef1234';
  

• オブジェクトおよび配列の定数

  単数形で、大文字で始め、const アサーションを付けます。

  const IDLE_ORDER = {
    pending: 'idle',
    fulfilled: true,
    error: 'Shipping Error',
  } as const;
  
  const DASHBOARD_ACCESS_ROLES = ['admin', 'editor', 'moderator'] as const;
  

  型がある場合は、Satisfies を使った型安全な定数を使用します。

  // Type OrderStatus is predefined (e.g. generated from database schema, API)
  type OrderStatus = {
    pending: 'pending' | 'idle';
    fulfilled: boolean;
    error: string;
  };
  
  const IDLE_ORDER = {
    pending: 'idle',
    fulfilled: true,
    error: 'Shipping Error',
  } as const satisfies OrderStatus;
  
  // Type UserRole is predefined
  type UserRole = 'admin' | 'editor' | 'moderator' | 'viewer' | 'guest';
  
  const DASHBOARD_ACCESS_ROLES = ['admin', 'editor', 'moderator'] as const satisfies ReadonlyArray<UserRole>;
  

関数 {#functions-1}

キャメルケース
filterProductsByType、formatCurrency

型 {#types-1}

パスカルケース
OrderStatus、ProductItem

{` '@typescript-eslint/naming-convention': [ 'error', { selector: 'typeAlias', format: ['PascalCase'], }, ]`}

ジェネリクス

ジェネリック型パラメーターは、大文字の T に説明的な名前を続けて始める必要があります（例：TRequest、TFooBar）。

主な理由と利点：

• 複雑な型ではジェネリクスがよく使われるため、明確な命名によって可読性と保守性が向上します。
• T、K、U のような1文字のジェネリクスは使用できません。パラメーターが増えるほど、取り違えやすくなります。
• 接頭辞に T を付けると、通常の型ではなくジェネリック型パラメーターであることがすぐに分かります。
• よくあるケースとして、<Request extends Request> のように、ジェネリックパラメーターが同名の既存の型をシャドーイングすることがあります。

{`'@typescript-eslint/naming-convention': [ 'error', { // Generic type parameter must start with letter T, followed by any uppercase letter. selector: 'typeParameter', format: ['PascalCase'], custom: { regex: '^T[A-Z]', match: true }, } ]`}

// ❌ Avoid naming generic parameters with one letter
const createPair = <T, K extends string>(first: T, second: K): [T, K] => {
  return [first, second];
};
const pair = createPair(1, 'a');

// ✅ Use descriptive names starting with capital T
const createPair = <TFirst, TSecond extends string>(first: TFirst, second: TSecond): [TFirst, TSecond] => {
  return [first, second];
};
const pair = createPair(1, 'a');

// ❌ Avoid naming generic parameters without a prefix - which 'Request' is which?
const handle = <Request extends Request>(req: Request): void => {...

// ✅ Prefix generic parameter with capital T
const handle = <TRequest extends Request>(req: TRequest): void => {...

略語と頭字語

頭字語は一つの単語として扱い、最初の文字だけを大文字にします。

// ❌ Avoid
const FAQList = ['qa-1', 'qa-2'];
const generateUserURL(params) => {...}

// ✅ Use
const FaqList = ['qa-1', 'qa-2'];
const generateUserUrl(params) => {...}

読みやすさを高めるため、広く受け入れられていて必要な場合を除き、略語の使用は避けてください。

// ❌ Avoid
const GetWin(params) => {...}

// ✅ Use
const GetWindow(params) => {...}

React コンポーネント

パスカルケース
ProductItem、ProductsPage

Prop の型

React コンポーネント名の後ろに「Props」サフィックスを付けます
[ComponentName]Props - ProductItemProps、ProductsPageProps

コールバック Props

イベントハンドラー（コールバック）の props には on* を接頭辞として付けます（例：onClick）。
イベントハンドラーの実装関数には handle* を接頭辞として付けます（例：handleClick）。

{'react/jsx-handler-names': [ 'error', { eventHandlerPrefix: 'handle', eventHandlerPropPrefix: 'on', }, ]}

// ❌ Avoid inconsistent callback prop naming
<Button click={actionClick} />
<MyComponent userSelectedOccurred={triggerUser} />

// ✅ Use prop prefix 'on*' and handler prefix 'handle*'
<Button onClick={handleClick} />
<MyComponent onUserSelected={handleUserSelected} />

React Hooks

<Rule prefix="キャメルケースで、'use' を接頭辞として付けます" href="https://github.com/facebook/react/tree/main/packages/eslint-plugin-react-hooks"

{'react-hooks/rules-of-hooks': 'error'} <Rule prefix="対称的な規約：[value, setValue] = useState()" href="https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/hook-use-state.md#rule-details" {'react/hook-use-state': 'error'}

// ❌ Avoid inconsistent useState hook naming
const [userName, setUser] = useState();
const [color, updateColor] = useState();
const [isActive, setActive] = useState();

// ✅ Use
const [name, setName] = useState();
const [color, setColor] = useState();
const [isActive, setIsActive] = useState();

カスタムフックは常にオブジェクトを返す必要があります。

// ❌ Avoid
const [products, errors] = useGetProducts();
const [fontSizes] = useTheme();

// ✅ Use
const { products, errors } = useGetProducts();
const { fontSizes } = useTheme();

コメント

コメントはすぐに古くなり、明確さをもたらすどころか混乱を招くことがあります。

意味のある名前と明確なロジックを使い、コメントよりも表現力のあるコードを優先してください。コメントでは、主に「何を」や「どのように」ではなく、「なぜ」を説明します。

次の場合にコメントを使用します。

• コードだけでは背景や理由が明らかでない場合（例：設定ファイル、回避策）
• 関連するイシュー、PR、または予定されている改善に言及する場合

// ❌ Avoid
// convert to minutes
const m = s * 60;
// avg users per minute
const myAvg = u / m;

// ✅ Use - Prefer expressive code by naming things what they are
const SECONDS_IN_MINUTE = 60;
const minutes = seconds * SECONDS_IN_MINUTE;
const averageUsersPerMinute = noOfUsers / minutes;

// ✅ Use - Reference planned improvements
// TODO: Move filtering to the backend once API v2 is released.
// Issue/PR - https://github.com/foo/repo/pulls/55124
const filteredUsers = frontendFiltering(selectedUsers);

// ✅ Use - Add context to explain why
// Use Fourier transformation to minimize information loss - https://github.com/dntj/jsfft#usage
const frequencies = signal.FFT();

TSDoc コメント

TSDoc は TypeScript のドキュメントコメントを標準化し、エディターやドキュメントツールが一貫して解釈できるようにします。これにより開発者体験が向上し、生成される API ドキュメントにも対応できます。

API、ライブラリ、設定、または再利用可能なコードをドキュメント化する際は、TSDoc コメントを使用します。

/**
 * Configuration options for the Web3 SDK.
 */
export type Web3Config = {
  /** Ethereum network chain ID. */
  chainId: number;

  /**
   * Gas price strategy for transactions:
   * - `fast`: Higher fees, faster confirmation
   * - `standard`: Balanced
   * - `slow`: Lower fees, slower confirmation
   */
  gasPriceStrategy: 'fast' | 'standard' | 'slow';

  /** Maximum gas limit per transaction. */
  maxGasLimit?: number;

  /** Enables event listening for smart contract interactions. */
  enableEventListener?: boolean;
};