# OTUS ## Javascript / TypeScript <!--v--> ## Зачем документировать код? - Не про комментарии, а про **описание интерфейсов** и API - Повышает читаемость и сопровождение - Улучшает работу команды и вхождение в проект - Используется IDE и автокомплитом <!--v--> ## Что включает хорошая документация? - Назначение модуля/функции - Типы входных и выходных данных - Примеры использования - Указание особенностей или ограничений <!--v--> ## Именование: основа читаемости - **Функции**: глаголы (`getUser`, `calculateTotal`) - **Модули**: предметная область (`authService`, `logger`) - **Переменные**: - булевы: `isValid`, `hasPermission` - коллекции: `users`, `items` - константы: `MAX_LENGTH`, `DEFAULT_TIMEOUT` <!--v--> ## Примеры наименований | Плохо | Хорошо | | --------- | ------------------ | | `data()` | `fetchUserData()` | | `check()` | `isAuthorized()` | | `calc()` | `calculatePrice()` | <!--s--> ## Что такое JSDoc <!--v--> ### Определение и цели - JSDoc — способ аннотировать JS-код для понимания структуры и типов - Не требует TypeScript! - Работает в любом `.js` файле <!--v--> ### Пример JSDoc ```js /** * Складывает два числа * @param {number} a Первое число * @param {number} b Второе число * @returns {number} Сумма */ function add(a, b) { return a + b; } ``` <!--v--> ### Основные теги JSDoc - `@param` — параметры функции - `@returns` — возвращаемое значение - `@example` — пример использования - `@typedef` — объявление типа - `@deprecated`, `@see`, `@throws` и др. <!--v--> ### Как работает в редакторе - Подсказки и типы при наведении - Автокомплит параметров и возвращаемых значений - Можно использовать без TS! <!--s--> ## TypeScript и JSDoc <!--v--> ### Чем TypeScript лучше JSDoc | | JSDoc | TypeScript | | ----------- | ------------------- | -------------------- | | Простота | ✅ | ❌ требует настройку | | Проверка | ограничена | ✅ строгая проверка | | IDE-помощь | 👍 | 🔥 лучшее качество | | Рефакторинг | ❌ (часто ломается) | ✅ надёжный | <!--v--> ### Пример JSDoc и TS **JSDoc:** ```js /** @param {string} name */ function greet(name) { return "Hi, " + name; } ``` **TypeScript:** ```ts function greet(name: string): string { return "Hi, " + name; } ``` <!--v--> ### Гибридный режим - `.js` + JSDoc + `tsconfig.json` - Получаем линтинг и автотипизацию без перехода на `.ts` <!--s--> ## Генерация документации <!--v--> ### С помощью JSDoc ```bash npm install --save-dev jsdoc npx jsdoc src -r -d docs ``` - Генерирует HTML-документацию по комментариям <!--v--> ### С помощью TypeDoc (для TS) ```bash npm install --save-dev typedoc npx typedoc src ``` - Создаёт красивую документацию с ссылками между типами и интерфейсами <!--s--> ## TypeScript для линтинга JS <!--v--> ### Пример `tsconfig.json` ```json { "compilerOptions": { "allowJs": true, "checkJs": true, "noEmit": true, "strict": true }, "include": ["src"] } ``` <!--v--> ### Что даёт `checkJs` - TypeScript **проверяет** `.js` файлы - Учитывает типы из JSDoc - Показывает ошибки типов до выполнения <!--v--> ### Пример ошибки: ```js /** @param {number} x */ function double(x) { return x * "2"; // ❌ ошибка типов } ``` <!--s--> ## Выводы <!--v--> - Документация = ясное API, а не просто комментарии - JSDoc помогает даже без TypeScript - TS усиливает надёжность и масштабируемость - Документацию можно генерировать автоматически - TypeScript умеет проверять `.js`-файлы с JSDoc <!--v--> ### Вопросы? 🙋‍♀️🙋‍♂️