Ревью читаемости кода

Ревью читаемости {{scope}}.

1. Длина и вложенность

Найди функции / файлы превышающие. Они кандидаты на разбиение.

2. Early returns vs пирамида

// плохо
if (user) {
  if (user.active) {
    if (user.permission === 'admin') {
      // делаем
    }
  }
}

// хорошо
if (!user) return null;
if (!user.active) return null;
if (user.permission !== 'admin') return null;
// делаем

3. Имена

См. отдельный промт "Улучшение имён". Здесь же — флажки:

• Сокращения без объяснения
• Имена-помойки: data, info, temp, obj
• Boolean без is/has/can префикса
• Функция process() — что она делает?

4. Комментарии

// плохо: дублирует код
// increment i
i++;

// плохо: устарел
// returns user by email
function findById(id) { ... }

// хорошо: объясняет ПОЧЕМУ
// We bump TTL by 5min because Redis cache miss
// causes a thundering herd on cold cache.
cache.set(key, value, ttl + 300);

Правила:

• Хороший код объясняет себя именами. Комментарий — для почему, не что
• TODO / FIXME — с автором и датой: // TODO(alice, 2025-04): refactor when X lands
• Устаревшие комментарии хуже отсутствующих

5. Магические числа и строки

// плохо
if (status === 3) { ... }
setTimeout(fn, 86400000);

// хорошо
const STATUS_APPROVED = 3;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;

6. Структура файла

Сверху вниз должно читаться как история:

1. Импорты
2. Типы
3. Константы
4. Главный экспорт
5. Хелперы (внизу)

Не вынуждай прыгать вверх-вниз чтобы понять main.

7. Зависимости

• Сколько импортов в файле? > 20 — много, что-то делает слишком много
• Циклические зависимости — нет
• Прямые импорты из internals других модулей — нет

8. Боль "тыкать в каждое определение"

Если приходится Cmd+Click на каждой строчке чтобы понять что происходит — слишком много абстракции. Может быть, можно inline.

Отчёт

## Топ-5 проблем читаемости
1. [файл:строка] [что] — почему мешает читать — как исправить

## Метрики
| Метрика | Значение | Цель |

## Что хорошо
- ...

Принципы

• Код читают в 10 раз чаще чем пишут
• "Умный" код плох. Простой — хорош
• Если объяснил коллеге одну функцию 30 секунд — норм. 5 минут — переписывай