no-type-in-docs

ドキュメントで型情報を繰り返さない

概要

型注釈がドキュメントです。コメントで重複させないでください。

型についてのコメントは、コードと食い違うようになります。TypeScript の型システムは簡潔で読みやすく設計されています。型のドキュメントとして、まず型システムを使いましょう。

このスキルを使う場面

• 関数の JSDoc やコメントを書くとき
• パラメーターの型をドキュメント化するとき
• 変数に名前を付けるとき
• 戻り値を説明するとき

絶対ルール

Never put type information in comments.
Let the type annotations speak for themselves.

覚えておきましょう：

• コメントはコードと食い違うようになりますが、型はチェックされます
• 型注釈は読みやすく設計されています
• コメントでは型の WHAT ではなく WHY を説明します
• 変数名に型情報を含めてはいけません

検出：コメント内の型情報

/**
 * Returns a string with the foreground color.
 * Takes zero or one arguments. With no arguments, returns the
 * standard foreground color. With one argument, returns the foreground color
 * for a particular page.
 */
function getForegroundColor(page?: string) {
  return page === 'login' ? {r: 127, g: 127, b: 127} : {r: 0, g: 0, b: 0};
}

問題点：

• コメントには「文字列を返す」とありますが、関数はオブジェクトを返します
• パラメーター数の説明はシグネチャを見ればわかります
• コメントが実装より長くなっています！

より良いドキュメント

/** Get the foreground color for the application or a specific page. */
function getForegroundColor(page?: string): Color {
  // ...
}

型シグネチャから、次のことがわかります。

• パラメーターは省略可能な文字列です
• 戻り値の型は Color です
• コメントで繰り返す必要はありません

非変更性をドキュメント化しない

// Bad: comment lies (sort() mutates in place)
/** Sort the strings by numeric value. Does not modify nums. */
function sortNumerically(nums: string[]): string[] {
  return nums.sort((a, b) => Number(a) - Number(b));
}

// Good: type enforces non-mutation
/** Sort the strings by numeric value. */
function sortNumerically(nums: readonly string[]): string[] {
  return nums.toSorted((a, b) => Number(a) - Number(b));
}

readonly 修飾子は TypeScript によって強制されます。コメントにはそのような強制力がありません。

変数名

変数名に型を含めないでください。

// Bad: redundant type in name
const ageNum = 30;
const nameString = 'Alice';
const usersArray = [];

// Good: descriptive names, types inferred
const age = 30;
const name = 'Alice';
const users = [];

例外：単位

型からわからない場合は、単位を含めてください。

// Good: units aren't captured by type
const timeMs = 1000;
const temperatureC = 20;
const distanceKm = 5.5;

// Better: use branded types (Item 64)
type Milliseconds = number & { _brand: 'ms' };
const time: Milliseconds = 1000 as Milliseconds;

JSDoc のベストプラクティス

型情報ではなく、パラメーターの説明には @param を使います。

/**
 * Formats a user's display name.
 * @param user - The user to format
 * @param options - Formatting options
 * @returns The formatted display name
 */
function formatDisplayName(
  user: User,
  options?: FormatOptions
): string {
  // ...
}

型情報を重複させないでください。

// Bad: duplicates types
/**
 * @param user {User} - The user object
 * @param options {FormatOptions | undefined} - Optional formatting options
 * @returns {string} The formatted name
 */

コメントに含めるべき内容

• 目的と意図
• ビジネスロジックの説明
• アルゴリズムの説明
• 自明でない動作
• 関連ドキュメントへのリンク

/**
 * Calculates compound interest using the standard formula.
 * See: https://en.wikipedia.org/wiki/Compound_interest
 */
function compoundInterest(
  principal: number,
  rate: number,
  periods: number
): number {
  // P(1 + r)^n
  return principal * Math.pow(1 + rate, periods);
}

プレッシャーへの対処プロトコル

1. 「コメントがあればコードが読みやすくなる」

プレッシャー：「わかりやすくするために型をドキュメント化したい」

回答： 型はドキュメントです。チェックされ、常に正確です。

対応： コメントから型情報を削除します。わかりにくい場合は型名を改善します。

2. 「複雑な型をドキュメント化する必要がある」

プレッシャー：「型が複雑なので、説明する必要があります」

回答： 型定義そのものに TSDoc を使います。

対応： 使用箇所ではなく、型にドキュメントを追加します。

危険信号 — 手を止めて再検討する

• 「文字列を返す」などの記述がコメントにある
• コメントにパラメーター数が記載されている
• 「変更しない」という主張がある（代わりに readonly を使う）
• numUsers や strName のような変数名

よくある正当化（どれも誤り）

言い訳	実際のところ
「そのほうが読みやすい」	型は読みやすく設計されています
「TypeScript を知らない人もいる」	ホバーまたはクリックすれば型を確認できます
「ドキュメントはあればあるほどよい」	古くなったドキュメントは有害です

クイックリファレンス

// DON'T: Type info in comments
/** Returns string, takes number */ 
function f(n: number): string { ... }

// DON'T: Claim non-mutation in comments
/** Does not modify array */
function sort(arr: number[]): number[] { ... }

// DON'T: Types in variable names
const ageNum = 30;

// DO: Describe purpose, not types
/** Get display name for UI header */
function getName(user: User): string { ... }

// DO: Use readonly for non-mutation
function sort(arr: readonly number[]): number[] { ... }

// DO: Units in names when helpful
const timeMs = 1000;

要点

型注釈がドキュメントです。

TypeScript の型システムは表現力が高く、常に正確です。型についてのコメントはコードと食い違うようになり、読者を誤解させます。コメントは型ではなく、目的、意図、ビジネスロジックの説明に使いましょう。

参考資料

Dan Vanderkam 著「Effective TypeScript」の項目 31「ドキュメントで型情報を繰り返さない」に基づいています。