Writing JavaScript and TypeScript Comments for Collaboration with JSDoc

📅

loading..🐩🐩🐩🐩

Before getting started 🔗

Why comments matter 🔗

Readability and maintainability are important in software development.

In collaborative projects, code alone often does not make the author's intent clear.

Recently, I have been responsible for defining conventions at work and have thought about how to make code easier for teammates to understand.

While inspecting npm modules, I often found configuration files consisting of more comments than code, and realized how much those comments helped me understand them.

This article explores writing comments in JavaScript and TypeScript, especially for collaboration.

What is JSDoc? 🔗

JSDoc↗ is a way to document JavaScript code, explaining its meaning and usage.

An IDE can extract and display information from these comments, making the code easier to understand.

They can also generate API documentation automatically.

The following image shows the information VS Code displays when hovering over Next.js's Link component.

It comes from JSDoc comments and includes parameters, return values, and even prose explanations.

Use JSDoc to standardize comments in JavaScript and TypeScript so collaborators can understand the purpose and usage of code.

This article covers

JSDoc's basic syntax and usage

and

effective documentation for collaboration

1. Basic JSDoc syntax 🔗

JSDoc is a JavaScript and TypeScript comment style used to communicate code meaning clearly.

The basic format is as follows.

/** @type {string} */
var win;

The /** ... */ format denotes a JSDoc comment.

For a function, write it as follows.

/**
* 책의 정보를 나타내는 함수입니다.
* @constructor
* @param {string} title - 책의 제목
* @param {string} author - 책의 저자
*/
function Book(title: string, author: string) {
}

Use a /** ... */ comment block.
Briefly explain the function's purpose on the first line.
Use @param to describe the type and role of each parameter.
Use @returns to describe the type and meaning of the returned value.

The IDE can then display type information and explanations automatically, helping developers understand the code.

2. Additional JSDoc tags 🔗

JSDoc supports many tags.

Here are some other frequently useful ones.

2.1. @example: Usage examples 🔗

/**
 * 숫자를 세제곱합니다.
 * @param {number} x - 입력 숫자
 * @returns {number} x의 세제곱 값
 * @example
 * cube(3); // 27
 */
function cube(x: number): number {
  return x * x * x;
}

2.2. @deprecated: Marking obsolete functions 🔗

/**
 * 이 함수는 더 이상 사용되지 않습니다. 대신 newMethod를 사용하세요.
 * @deprecated
 */
function oldMethod() {
  console.log("이 메서드는 더 이상 사용되지 않습니다.");
}

2.3. @throws: Documenting exceptions 🔗

/**
 * 숫자를 나눕니다.
 * @param {number} x - 나눌 숫자
 * @param {number} y - 나누는 숫자
 * @returns {number} x를 y로 나눈 값
 * @throws {DivideByZero} y가 0인 경우
 */
function divide(x: number, y: number): number {
	if (y === 0) {
		throw new Error("y는 0이 될 수 없습니다.");
	}
	return x / y;
}

2.4. @async: Marking asynchronous functions 🔗

/**
 * 비동기적으로 사용자 정보를 가져옵니다.
 * @param {string} userId - 사용자 ID
 * @returns {Promise<User>} 사용자 정보
 * @async
 */
async function fetchUser(userId: string): Promise<User> {
	const response = await fetch(`/users/${userId}`);
	return response.json();
}

2.5. @typedef: Defining a type 🔗

/**
 * 숫자 또는 숫자가 포함된 문자열입니다.
 * @typedef {(number|string)} NumberLike
 */
 
/**
 * 매직넘버를 설정합니다.
 * @param {NumberLike} x - 매직넘버.
 */
 function setMagicNumber(x: NumberLike) {
}

Conclusion 🔗

Writing good comments is more than a habit; it is an essential part of building a better development culture.

Further questions 🔗

Could too many comments actually harm code readability?

References 🔗

Writing JavaScript and TypeScript Comments for Collaboration with JSDoc | PromleeBlog