Документировал ли код

Документирование кода

Документирование — это процесс описания того, что делает код, почему он так работает, и как его использовать. Это критически важно для поддержки проекта, особенно в backend-разработке, где код работает в production.

Почему документирование важно

• Снижение кривой обучения: новые разработчики быстро разбираются в проекте
• Снижение ошибок: понимание логики предотвращает баги
• Облегчение рефакторинга: известны все побочные эффекты
• Пример хорошего стиля: показывает junior-разработчикам, как писать код
• Production требование: в боевых системах без доков — хаос

Типы документирования

1. Комментарии в коде (inline documentation)

Объясняют почему, а не что:

// ❌ Плохо — объясняет очевидное
const age = user.birthDate; // Получаем дату рождения
const years = new Date().getFullYear() - age.getFullYear(); // Вычисляем возраст

// ✅ Хорошо — объясняет нетривиальную логику
// Используем getFullYear(), чтобы избежать проблем с високосными годами
// и различиями в месяцах при вычислении точного возраста
const age = calculateAgeIgnoringBirthdayMonth(user.birthDate);

2. JSDoc комментарии (function documentation)

Описывают параметры, возвращаемые значения и примеры:

/**
 * Создаёт нового пользователя в системе
 * 
 * @param {string} email - Уникальный email пользователя
 * @param {string} password - Пароль (минимум 8 символов)
 * @param {Object} profile - Профиль пользователя
 * @param {string} profile.firstName - Имя
 * @param {string} profile.lastName - Фамилия
 * @returns {Promise<User>} Созданный пользователь с ID
 * @throws {ValidationError} Если email некорректный или уже существует
 * @throws {PasswordError} Если пароль не соответствует требованиям
 * 
 * @example
 * const user = await createUser('john@example.com', 'password123', {
 *   firstName: 'John',
 *   lastName: 'Doe'
 * });
 * console.log(user.id); // UUID
 */
async function createUser(email, password, profile) {
  // реализация
}

3. README файлы

Описание проекта на уровне модуля:

# User Service

Микросервис для управления пользователями.

## Установка

\`\`\`bash
npm install
\`\`\`

## Использование

\`\`\`javascript
const service = new UserService();
await service.createUser(userData);
\`\`\`

## API

### createUser(email, password)

Создаёт нового пользователя.

- **email** (string): Уникальный email
- **password** (string): Минимум 8 символов
- **Returns**: Promise<User>

\`\`\`javascript
const user = await service.createUser('john@example.com', 'pass123');
\`\`\`

4. Architecture Documentation

Описание общей архитектуры системы:

# Архитектура проекта

## Слои

1. **Presentation** — API endpoints (FastAPI, Express)
2. **Application** — Use cases, бизнес-логика
3. **Domain** — Entity, Value Objects
4. **Infrastructure** — Database, External APIs

## Data Flow

Request → Handler → UseCase → Service → Repository → Database

## Database Schema

[Диаграмма ERD]

## API Routes

POST /api/v1/users — Создание пользователя
GET /api/v1/users/{id} — Получение пользователя

Backend-специфичные практики

Документирование API endpoints

/**
 * Получить информацию о пользователе
 * 
 * @route GET /api/v1/users/:id
 * @param {string} id - UUID пользователя
 * @returns {Object} User object
 * @returns {number} User.id
 * @returns {string} User.email
 * @returns {Object} User.profile
 * 
 * @example
 * GET /api/v1/users/550e8400-e29b-41d4-a716-446655440000
 * 
 * Response (200):
 * {
 *   "id": "550e8400-e29b-41d4-a716-446655440000",
 *   "email": "john@example.com",
 *   "profile": {
 *     "firstName": "John",
 *     "lastName": "Doe"
 *   }
 * }
 * 
 * @throws {NotFoundError} 404 - Пользователь не найден
 * @throws {UnauthorizedError} 401 - Требуется авторизация
 */
router.get('/users/:id', async (req, res) => {
  // реализация
});

Документирование сложной бизнес-логики

/**
 * Подбирает оппонента для игры
 * 
 * Алгоритм:
 * 1. Получаем список активных игроков с рейтингом близким к нашему (±100 пунктов)
 * 2. Используем SELECT FOR UPDATE SKIP LOCKED для предотвращения race conditions
 * 3. Выбираем первого доступного (предотвращает deadlock)
 * 4. Обновляем статус обоих в одной транзакции
 * 5. Если никого нет, ставим в очередь ожидания
 * 
 * Race Condition Prevention:
 * - SKIP LOCKED гарантирует, что мы не заблокируемся
 * - Строгий порядок блокировок предотвращает deadlock
 * - Транзакция гарантирует атомарность
 * 
 * @param {string} userId
 * @returns {Promise<Game>} Созданная игра или null если нет оппонента
 */
async function findOpponent(userId) {
  // реализация с SELECT FOR UPDATE SKIP LOCKED
}

Документирование миграций БД

-- 0001_create_users_table.sql
-- Создание таблицы пользователей
-- 
-- Причина: Для хранения информации о пользователях системы
-- 
-- ВАЖНОЕ: При удалении пользователя используется CASCADE для очистки всех связанных данных
-- (посты, комментарии, лайки). Это требует внимания при work_on_legacy_data.
-- 
-- Indexed fields для быстрого поиска:
-- - email: для уникальности и логина
-- - created_at: для сортировки по времени

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) NOT NULL UNIQUE,
  password_hash VARCHAR(255) NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_created_at ON users(created_at);

Инструменты

Swagger/OpenAPI для документирования API:

import swaggerJsdoc from 'swagger-jsdoc';

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
};

const specs = swaggerJsdoc(options);
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(specs));

Золотые правила документирования

1. Документируй почему, не что — код показывает что, документация объясняет почему
2. Поддерживай документацию в актуальности — устаревшая документация хуже, чем её отсутствие
3. Примеры обязательны — код лучше слов
4. Документируй граничные случаи — что происходит с null, пустыми массивами, ошибками?
5. Используй стандарты — JSDoc, Swagger, Markdown, делает код единообразным

Хорошо задокументированный код — это профессиональный код, который живёт долго и работает надёжно в production.