When should you add type annotations?

An annotation is a contract. It tells the compiler and the reader what a value is supposed to be, and the compiler checks that assignments and calls respect it. Because annotations are erased, they have no runtime cost, but an inaccurate annotation can give false confidence.

function parseCount(input: string): number {
  const value = Number(input);

  if (Number.isNaN(value)) {
    throw new Error("Invalid count");
  }

  return value;
}

const total: number = parseCount("42");

Where annotations earn their keep

• Exported function parameters and return types
• Public class fields and method signatures
• Variables that start as null or undefined and are assigned later
• Callbacks whose parameter type cannot be inferred from context
• Data structures that are intentionally wider than their initial value

For local variables, inference is usually clearer. Writing const total: number = 0 next to const total = 0 adds noise without adding safety. The exception is when the initial value would infer a narrower type than the variable is meant to hold later.