TypeScript Comments: Syntax, Usage, and Examples

TypeScript comments are essential tools for improving code readability, documenting logic, and assisting in collaborative development. Like JavaScript, TypeScript supports single-line and multi-line comments, but its static typing and tooling further enhance the usefulness of comments. Knowing how to comment in TypeScript effectively is crucial for clean, maintainable code.

This guide covers the different types of TypeScript comments, where and how to use them, best practices, and how comments integrate with tools like TSDoc and IDEs.

What Are TypeScript Comments?

Comments in TypeScript are non-executable annotations embedded within the code to explain its behavior or mark sections for future reference. They do not affect runtime execution but serve as guidance for developers. TypeScript comments can describe code functionality, provide context, or temporarily disable blocks during debugging.

Since TypeScript is a superset of JavaScript, the syntax for comments remains the same. However, the use of comments in TypeScript is more structured due to its support for documentation tools like TSDoc.

Why Use Comments in TypeScript?

Strategically placed comments help you and your team understand complex logic, track changes, and reduce the learning curve for new contributors. Here are the main benefits of using TypeScript comments:

• Improve code readability by explaining intent and logic
• Serve as in-line documentation for functions, classes, and modules
• Assist in debugging and testing by isolating code blocks
• Enhance IDE tooltips and API documentation with structured comments
• Provide context for type declarations and interfaces

While TypeScript already improves code clarity with types, comments are invaluable for describing the "why" behind decisions.

Types of TypeScript Comments

TypeScript supports three main types of comments: single-line, multi-line, and documentation comments.

Single-Line Comments

These start with // and continue to the end of the line. Use them for brief explanations or to disable specific lines temporarily.

// This variable holds the user's age
let age: number = 25;

Multi-Line Comments

Enclosed between /* and */, these are useful for longer explanations or block commenting during debugging.

/*
  This function calculates the area of a rectangle.
  It takes two numeric parameters: width and height.
*/
function getArea(width: number, height: number): number {
  return width * height;
}

Documentation Comments (TSDoc)

These structured comments begin with /** and are parsed by documentation generators and IDEs. They allow you to describe parameters, return types, exceptions, and more.

/**
 * Calculates the square of a number.
 * @param value - The number to square
 * @returns The squared result
 */
function square(value: number): number {
  return value * value;
}

Tools like TypeDoc and editors like VS Code can display these comments during hover or autocomplete.

How to Comment in TypeScript Code Effectively

Here are typical scenarios and methods for adding comments to your TypeScript code.

Commenting Out Code During Debugging

Temporarily disable sections of code without deleting them:

// console.log("Debug info");

Explaining Complex Logic

Use clear, concise language to explain non-obvious code behavior:

// Using bitwise operator to check flags
let isActive: boolean = (flags & 1) === 1;

Annotating Types and Interfaces

Provide explanations for custom types:

// User type includes email and optional age
interface User {
  email: string;
  age?: number;
}

Commenting Functions and Methods

Document purpose, parameters, and return values:

/**
 * Filters an array of numbers.
 * @param nums - Array of integers
 * @returns Filtered array with values > 10
 */
function filterHigh(nums: number[]): number[] {
  return nums.filter(num => num > 10);
}

Commenting Best Practices in TypeScript

Using TypeScript comments effectively requires more than just syntax. Follow these best practices:

Be Clear and Concise

Avoid vague or overly verbose comments. Aim for helpful explanations.

Keep Comments Up to Date

Update or remove outdated comments. Stale comments can mislead readers.

Don’t Explain the Obvious

Avoid commenting on code that is self-explanatory.

// Increment i by 1  ← unnecessary
i++;

Use Documentation Comments for Public APIs

When creating reusable libraries or components, add structured documentation.

Comment the “Why”, Not Just the “What”

Focus on why something is done, especially if the logic is unconventional.

// Using manual loop instead of map for performance in large datasets

TypeScript Tooling and Comments

TypeScript comments are integrated with several tools:

IDE Support

Modern editors like Visual Studio Code show comments as tooltips and support inline documentation through TSDoc.

TypeDoc

TypeDoc generates HTML documentation from TypeScript source code, leveraging documentation comments.

ESLint

Linters can enforce comment conventions and warn about commented-out code or missing documentation.

Special Comment Directives

TypeScript recognizes certain comment patterns as directives:

@ts-ignore

Tells the compiler to ignore the next line.

// @ts-ignore
let total: number = "not a number";

Use sparingly, as it disables type safety.

@ts-expect-error

Indicates that an error is expected on the next line.

// @ts-expect-error: This assignment is intentionally invalid
let username: string = 123;

This directive helps catch removed or fixed errors in future code.

Summary

TypeScript comments play a vital role in writing maintainable, well-documented, and team-friendly code. From single-line notes to full-fledged documentation blocks, comments in TypeScript improve understanding and clarity.

By mastering how to comment in TypeScript and following best practices, developers can make their codebases more robust, collaborative, and easy to maintain. Whether you’re working solo or as part of a team, the right comments make all the difference.