📘 JSDoc – ваш помощник в разработке. Убедитесь сами!

Если вы пишете на JavaScript или TypeScript, то, скорее всего, сталкивались с /** … */ над функциями. Это не просто комментарии — это JSDoc.

И он может сделать вашу жизнь и ваших коллег намного проще.

🤔 Что такое JSDoc

JSDoc — это инструмент для документирования JavaScript-кода. С его помощью можно:

описывать функции, классы и переменные,
указывать типы данных,
генерировать HTML-документацию,
и главное — получать автокомплит и типизацию прямо в редакторе.

📚 Официальная документация: jsdoc.app

✅ Где JSDoc реально помогает

🔹 1. Функции и методы

/**
 * Рассчитывает цену товара с учётом скидки.
 * @param {number} originalPrice - Изначальная цена (должна быть > 0).
 * @param {number} discountPercent - Процент скидки (от 0 до 100).
 * @returns {{ finalPrice: number, error: string | null }} - Объект с итоговой ценой и ошибкой (если есть).
 * @example
 * calculateDiscount(1000, 20); // { finalPrice: 800, error: null }
 * calculateDiscount(-50, 10);  // { finalPrice: 0, error: "Цена должна быть больше 0" }
 */
function calculateDiscount(originalPrice, discountPercent) {
	if (originalPrice <= 0) {
		return { finalPrice: 0, error: 'Цена должна быть больше 0' };
	}
 
	if (discountPercent < 0 || discountPercent > 100) {
		return { finalPrice: originalPrice, error: 'Скидка должна быть от 0% до 100%' };
	}
 
	const finalPrice = originalPrice * (1 - discountPercent / 100);
	return { finalPrice: Number(finalPrice.toFixed(2)), error: null };
}

➡️ В редакторе сразу появляется подсказка, и вам (и вашим коллегам) не нужно лезть в реализацию.

🔹 2. Документация API и SDK

JSDoc идеально подходит для описания публичных методов, классов и интерфейсов, особенно если вы разрабатываете SDK, библиотеку или внутренний API.

🔹 3. Поддержка типизации в JS-проектах

Если вы не используете TypeScript, JSDoc — это лёгкий способ добавить типы без пересборки проекта.

🚫 Когда JSDoc — лишний

В маленьких pet-проектах.
Когда код очевиден и легко читается без описания.
В коротких функциях (типа const double = (x) => x * 2).

📌 Главное — не превращать JSDoc в бюрократию и обязаловку. Он нужен там, где реально помогает.

⚙️ Как начать

Просто начните писать комментарии в формате /** */ и добавляйте теги:

@param — параметры
@returns — возвращаемое значение
@typedef — объявление типа
@property — свойства объекта
@example — пример использования

Больше тегов: jsdoc.app/tags.html

📝 Вывод

Это ваш помощник в командной разработке, автокомплите и понимании кода.

📌 JSDoc существенно упрощает поддержку кода, особенно в больших проектах. Без него сложные функции становятся “загадкой” для других разработчиков (и для вас через полгода😉).

✍️ Попробуйте описать 1-2 ключевые функции в проекте с помощью JSDoc — и вы сами убедитесь, как удобно это становится.

📢 Не игнорируйте его. Используйте с умом — и коллеги отблагодарят вас, так как качество читаемости вашего кода и скорость их разработки возрастет.