Don't Repeat Type Information in Documentation

Overview

Type annotations are your documentation. Don't duplicate them in comments.

Comments describing types get out of sync with code. TypeScript's type system is designed to be compact and readable - use it as your primary source of type documentation.

When to Use This Skill

Writing JSDoc or comments for functions
Documenting parameter types
Naming variables
Describing return values

The Iron Rule

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

Remember:

Comments drift out of sync; types are checked
Type annotations are designed to be readable
Comments should explain WHY, not WHAT type
Variable names shouldn't include type info

Detection: Type Info in Comments

/**
 * 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};
}

Problems:

Comment says "returns a string" but function returns an object
Comment describes parameter count (visible in signature)
Comment is longer than the implementation!

Better Documentation

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

The type signature tells you:

Parameter is optional string
Return type is Color
No need to repeat this in comments

Don't Document Non-Mutation

// 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));
}

The readonly modifier is enforced by TypeScript. Comments are not.

Variable Names

Don't include types in variable names:

// 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 = [];

Exception: Units

Include units when not obvious from type:

// 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 Best Practices

Use @param for parameter documentation, not type info:

/**
 * 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 {
  // ...
}

Don't duplicate type information:

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

What Comments SHOULD Include

Purpose and intent
Business logic explanations
Algorithm descriptions
Non-obvious behavior
Links to relevant documentation

/**
 * 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);
}

Pressure Resistance Protocol

1. "Comments Make Code More Readable"

Pressure: "I want to document types for clarity"

Response: Types ARE documentation. They're checked, always accurate.

Action: Remove type info from comments. Improve type names if unclear.

2. "I Need to Document Complex Types"

Pressure: "The type is complicated, I need to explain it"

Response: Use TSDoc on the type definition itself.

Action: Add documentation to the type, not the usage.

Red Flags - STOP and Reconsider

Comments mentioning "returns a string" or similar
Parameter count mentioned in comments
"Does not modify" claims (use readonly instead)
Variable names like numUsers or strName

Common Rationalizations (All Invalid)

Excuse	Reality
"It's more readable"	Types are designed to be readable
"Not everyone knows TypeScript"	They can hover/click to see types
"Documentation is always good"	Outdated documentation is harmful

Quick Reference

// 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;

The Bottom Line

Type annotations are your documentation.

TypeScript's type system is expressive and always accurate. Comments about types will drift out of sync and mislead readers. Use comments to explain purpose, intent, and business logic - not types.

Reference

Based on "Effective TypeScript" by Dan Vanderkam, Item 31: Don't Repeat Type Information in Documentation.

no-type-in-docs