Комментирование настроек

Конфигурационные файлы и объекты настроек требуют комментариев, когда значение не очевидно из названия или когда выбор конкретного значения продиктован нетривиальными соображениями.

Когда комментировать настройки

Комментарий оправдан, если:

  • Значение выбрано по нетехническим причинам (требования бизнеса, результаты A/B теста).
  • Нарушается общепринятое умолчание.
  • Значение зависит от внешнего условия (браузерная поддержка, производительность).
  • Без комментария следующий разработчик изменит значение и сломает что-то.

Правильный уровень комментирования

// Плохо — комментирует очевидное
const locale = 'ru'; // Устанавливает локаль на русский

// Хорошо — объясняет неочевидный выбор
const locale = 'ru'; // Только ru — остальные локали не входят в бандл (экономия ~8KB)

Пример конфига с обоснованными комментариями

const TIMEAGO_CONFIG = {
  // Интервал обновления: 45 000 мс вместо стандартных 60 000
  // Причина: пользователи жаловались, что "1 минуту назад" висит слишком долго
  // Результат A/B теста (июнь 2025): retention +3%
  updateInterval: 45_000,

  // Максимум 100 элементов: при 200+ заметна нагрузка на low-end устройства
  // Измерено в Chrome DevTools на Moto G4 (2025-05-15)
  maxElements: 100,

  // en_US, а не en: timeago.js требует именно этот ключ для английского
  // 'en' не зарегистрирован по умолчанию
  defaultLocale: 'en_US',
};

Комментирование LocaleFunc

register('ru_concise', (n, i) => {
  // Индексы 0-14 соответствуют временным интервалам от "только что" до "лет"
  // Полная таблица: timeago.js/README.md#locale-function
  const forms = [
    ['только что',  'сейчас'],     // 0: < 45 сек
    ['%s с назад',  'через %s с'], // 1: 1 сек
    ['%s с назад',  'через %s с'], // 2: 2-44 сек
    ['мин назад',   'через мин'],  // 3: 45-89 сек
    ['мин назад',   'через мин'],  // 4: 1-2 мин
    ['%s мин назад','через %s мин'],// 5: 2-44 мин
    ['ч назад',     'через ч'],    // 6: 45-89 мин
    ['ч назад',     'через ч'],    // 7: 1-2 ч
    ['%s ч назад',  'через %s ч'], // 8: 2-21 ч
    ['%s ч назад',  'через %s ч'], // 9: 22-35 ч
    ['вчера',       'завтра'],     // 10: 1-2 дня
    ['%s д назад',  'через %s д'], // 11: 2-25 дней
    ['%s д назад',  'через %s д'], // 12: 26-345 дней
    ['год назад',   'через год'],  // 13: 1-2 года
    ['%s лет назад','через %s лет'],// 14: > 2 лет
  ];
  return forms[i] ?? ['давно', 'скоро'];
});

Комментирование конфига Webpack/Vite

// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        // timeago.js вынесен в отдельный чанк:
        // - Библиотека обновляется редко → долгий браузерный кеш
        // - Размер ~2KB gzip не замедляет критический путь
        manualChunks: {
          timeago: ['timeago.js'],
        },
      },
    },
  },
};

Комментирование критических оптимизаций

// Кеш результатов format — предотвращает повторные вычисления
// при рендеринге списка из 500+ постов с одинаковыми датами.
// Без кеша: 500 вызовов format → ~25ms
// С кешем при 20% уникальных датах: 100 вызовов → ~5ms
const formatCache = new Map();

function cachedFormat(date, locale) {
  const key = `${date}:${locale}`;
  if (!formatCache.has(key)) {
    formatCache.set(key, format(date, locale));
  }
  return formatCache.get(key);
}

Что НЕ нужно комментировать

// Плохо — очевидно из кода
// Импортируем format из timeago.js
import { format } from 'timeago.js';

// Плохо — дублирует название функции
// Функция форматирует дату
function formatDate(date) { /* ... */ }

// Плохо — описывает что, а не почему
// Регистрируем русскую локаль
register('ru', ruLocale);

Хорошие комментарии для документации решений

// Используем format, а не render:
// Этот список генерируется сервером и кешируется CDN на 1 час.
// render создаст таймеры, которые будут обновлять устаревший кешированный HTML.
// Для статичного контента достаточно одноразового format при сборке страницы.
const posts = rawPosts.map(p => ({
  ...p,
  timeAgo: format(p.createdAt, 'ru'),
}));
Оглавление