Merge pull request #8 from JavaScript-Basic-OTUS/lesson12

Add lesson 12

Author: vvscode

lessons/lesson12/lesson.md

@@ -1 +1,217 @@
-# Lesson 12
+---
+title: Занятие 12
+description: "Работа с типами, JSDoc и TypeScript. Генерация документации и линтинг JS-файлов с типами"
+---
+
+# 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-->
+
+### Вопросы? 🙋‍♀️🙋‍♂️