Comments (// and /* */)

TypeScript has three types of comments: single-line comments (//), block comments (/* */), and JSDoc comments (/** */), which are widely used for documentation. Although TypeScript has a type system, JSDoc comments remain useful for describing intent, providing usage examples, and generating documentation. Editors such as VS Code read JSDoc and display the information on hover.

Syntax

// Single-line comment — everything from // to the end of the line is a comment.
const x = 10; // Inline comment — can also be written after code.

/*
  Block comment — everything between /* and */ is a comment.
  Use this when you want to write a comment that spans multiple lines.
*/

/**
 * JSDoc comment — a block comment that starts with /**.
 * Write this immediately before a function or class.
 * @param paramName - Description of the parameter
 * @returns Description of the return value
 */

Comment Types

Type	Syntax	Description
Single-line comment	// text	Everything from `//` to the end of the line becomes a comment. Also used to add a note to the right of a line of code.
Block comment	/* text */	Used when writing a comment that spans multiple lines. Cannot be nested.
JSDoc comment	/** text */	A special block comment that starts with `/**`. Documents information in a format that editors and documentation tools can parse. In TypeScript, type information lives in the code itself, so JSDoc is mainly used for descriptions and usage examples.

Common JSDoc Tags

JSDoc comments use tags starting with @ to document information. In TypeScript, type annotations in @param (e.g., {string}) can be omitted because the types are already in the code, but the descriptive text is still useful. Editors such as VS Code read JSDoc tags and display them on hover.

Tag	Description
@param name - description	Documents a function parameter. In TypeScript, the type annotation can be omitted since it is already in the code.
@returns description	Documents the return value of a function.
@throws description	Documents errors that may be thrown. Because TypeScript does not enforce exception types, making this explicit helps callers.
@template T	Documents a generic type parameter.
@deprecated description	Marks the item as deprecated. Most editors display the name with a strikethrough.
@see reference	Points to related functions or documentation.
@example	Provides a code block showing usage.
@internal	Used as a marker for tools such as TypeDoc to exclude the item from generated documentation.

When to Write Comments and When Not To

Decision	Situation	Reason
Write a comment	The reason why something was implemented a certain way	Design decisions and trade-offs that cannot be understood from the code alone help your future self and other developers.
Write a comment	Complex algorithms or formulas	Add a brief description of what a piece of logic does when its behavior is not immediately obvious at a glance.
Write a comment	Public API functions and classes	JSDoc comments on public APIs appear in editor hover tooltips and can be used by tools like TypeDoc to generate HTML documentation.
Write a comment	Non-obvious type casts or type assertions	Explaining why a type assertion (`as Type`) is used helps reviewers understand when it is safe to remove.
No comment needed	Logic that is obvious from reading the code	Self-evident explanations become noise. Clear variable, function, and type names remove the need for such comments.
No comment needed	Change history or deleted code	Because version control (git) is available, there is no need to keep old code or change dates in comments.

Sample Code

comment_basic.ts

// comment_basic.ts — Basic usage of TypeScript comment syntax.

interface Item {
    name: string;
    price: number;
}

// Define the item list
const items: Item[] = [
    { name: "widget", price: 1200 },
    { name: "gadget", price: 3500 },
    { name: "device", price: 800  },
];

/*
  Calculate the total and print the result.
  Use reduce to sum across the entire array.
*/
const total = items.reduce((sum, item) => sum + item.price, 0);

for (const item of items) {
    console.log(`${item.name.padEnd(10)} ${String(item.price).padStart(5)} yen`);
}

console.log("----------");
console.log(`${"Total".padEnd(10)} ${String(total).padStart(5)} yen`);

Running the above produces the following output:

$ npx ts-node comment_basic.ts
widget      1200 yen
gadget      3500 yen
device       800 yen
----------
Total       5500 yen

comment_jsdoc.ts

// comment_jsdoc.ts — Using JSDoc comments in TypeScript.

/**
 * Computes the average of a numeric array and returns it.
 *
 * Returns `null` if the array is empty (does not throw).
 *
 * @param values - An array of numbers to average
 * @returns The average (number), or null if the array is empty.
 * @example
 * ```ts
 * calculateAverage([85, 92, 78, 95, 60]); // 82
 * calculateAverage([]); // null
 * ```
 */
function calculateAverage(values: number[]): number | null {
    if (values.length === 0) {
        // Empty array cannot be averaged — return null
        return null;
    }

    const sum = values.reduce((acc, v) => acc + v, 0);
    return sum / values.length;
}

/**
 * @deprecated Use `calculateAverage` instead.
 */
function avg(values: number[]): number | null {
    return calculateAverage(values);
}

const scores = [85, 92, 78, 95, 60];
console.log("Average:", calculateAverage(scores));
console.log("Empty:  ", calculateAverage([]));

Running the above produces the following output:

$ npx ts-node comment_jsdoc.ts
Average: 82
Empty:   null

Overview

TypeScript has three comment types: single-line comments (//), block comments (/* */), and JSDoc comments (block comments starting with /**). Because TypeScript has a type system, parameter and return types can already be read from the code itself. Even so, JSDoc comments remain common practice for explaining intent, providing usage examples, and communicating constraints that types alone cannot express.

With JSDoc comments in place, editors such as VS Code display the documentation on hover. Tools like TypeDoc can also generate HTML documentation from JSDoc. The @deprecated tag causes most editors to display the name with a strikethrough, which is an effective way to signal to callers that an API is slated for removal.

If you find any errors or copyright issues, please contact us.

Home

TypeScript Dictionary