Джон, держи единый текст — ‘культура написания кода в команде’. Он строгий по смыслу, но человеческий по тону: про заботу, предсказуемость и общую выгоду, и включает всё, о чём мы говорили (декларативность, циклы, reduce, нейминг, ООП/наследование, return в конце с исключениями, async, TS-строгость, ошибки, правила ревью). Культура написания кода в команде (TypeScript, Node.js + Vue) Версия: 1.0 Статус: обязательна для нового кода и для изменений в существующем (правило ‘boy scout’: трогаешь — улучшаешь). Этот документ — не про ‘красиво’ и не про ‘как я привык’. Он про то, чтобы команда быстрее поставляла фичи, спокойнее дебажила, меньше уставала в ревью и не платила проценты по техдолгу. Код в репозитории — общий актив. Мы пишем его для коллег и для будущих себя. Чаще всего код читают, а не пишут. И читает его не автор, а человек без контекста: в спешке, на инциденте, через полгода, когда ‘память автора’ уже не существует. Поэтому наша базовая ценность — предсказуемость и читаемость. Личные предпочтения — нормальная человеческая штука. Но в командном коде они не могут быть главным аргументом. В ревью не работает ‘мне так нравится’, ‘я так привык’, ‘так моднее’, ‘так функциональнее’. Работают только аргументы, которые дают общую выгоду: — проще читать большинству команды; — проще дебажить (понятнее состояние, меньше скрытых веток); — проще расширять без переписывания; — меньше риск ошибок; — лучше типобезопасность; — есть ожидаемая/измеримая выгода по производительности. Если конструкция неочевидна — она должна быть оправдана контекстом. Не потому что мы ‘душним’, а потому что мы бережём время и нервы друг друга. 1) Базовый принцип: понятно важнее ‘умно’ Мы пишем код так, чтобы его можно было: — прочитать линейно и понять намерение; — безопасно менять без каскада побочных эффектов; — дебажить без прыжков по десяти выходам и скрытым мутациям. Если выбор между ‘красиво’ и ‘понятно’ — выбираем понятно. 2) Декларативность (что это значит у нас) Мы предпочитаем описывать намерение, а не ‘как именно бежим по индексам’. Норма: map / filter / find / some / every / flatMap. Но декларативность не должна превращаться в ‘цепочку ради цепочки’. Если цепочка становится длиннее 3–4 шагов и её тяжело читать — выносим части в именованные переменные/функции. Читатель должен понимать смысл, а не разгадывать головоломку. Побочные эффекты локализуем: — функции, которые ‘считают’, не должны внезапно писать в лог/метрики/внешнее состояние; — если побочный эффект нужен — он должен быть очевиден по имени и месту в коде. 3) Коллекции и циклы 3.1. Правило по умолчанию Для массивов используем методы массивов. Это делает код предсказуемым и одинаковым по проекту. 3.2. forEach — базовый выбор для действий forEach используем, когда мы делаем действие для каждого элемента и не строим новую структуру данных (логирование, вызов функции, накопление ошибок и т.п.). Важно: forEach не должен маскировать трансформации. Если вы строите новый массив — это map/filter. 3.3. map/filter/find/some/every — обязательны по смыслу — map: преобразование 1:1; — filter: отбор; — find: найти один элемент; — some/every: проверки. Запрещено писать ручной поиск/проверку через forEach с внешней переменной, если есть find/some/every. 3.4. for / for..of — разрешены, когда есть причина (и это нормально) for/for..of используем только если есть чёткая причина: — нужен break/continue; — участок ‘горячий’ (большие массивы, tight loop) и ожидается выигрыш; — нужно избежать лишних аллокаций/промежуточных массивов; — нужен последовательный async-проход. Идея простая: for — не ‘запрещён’, он ‘требует обоснования’. 3.5. reduce — строго и по делу reduce разрешён только когда это действительно свёртка коллекции в одно значение (число/строка/объект/Map/Record) и логика читается как ‘аккумулятор + элемент → новый аккумулятор’. reduce запрещён, когда: — он используется как замена filter + map ради ‘одного прохода’, но код становится менее читаемым; — он используется ради побочных эффектов (для этого есть forEach); — аккумулятор — массив, в который вы пушите, а по смыслу это обычные filter/map. Норма: — агрегации/суммы/словарь: reduce (или Object.fromEntries, если уместно); — фильтрация/проекция: filter + map. 3.6. Мутации и иммутабельность (без религии) — запрещено мутировать входные параметры функции; — локальная мутация внутри функции допустима, если она не ‘утекает’ наружу и делает код проще; — во Vue избегаем ‘магических’ мутаций, которые ломают реактивность: состояние меняем в ожидаемом месте (store/composable/component state). 4) Return в конце функции/метода 4.1. Основное правило По возможности функция/метод имеет один основной return в конце. 4.2. Зачем — линейное чтение; — проще дебажить (одна точка выхода); — меньше риска ‘вышли раньше и забыли важный шаг’. 4.3. Как пишем — используем переменную результата (result/response/nextState или доменное имя); — выполняем вычисления/подготовку; — возвращаем результат в конце. 4.4. Исключения (разрешены и считаются нормой) — валидация/guard clauses: ранние return допустимы, чтобы не раздувать вложенность; — ошибки: throw (или ваш Result/Either) — нормальный ранний выход; — очень короткие функции (1–3 строки), где ранний return не ухудшает читаемость. 4.5. Запрещено Делать ‘return в конце’ ценой адской вложенности. Если получается лабиринт из if — используем guard clauses. 5) Нейминг (строго, без креатива) Имена — это интерфейс для чтения. Мы называем так, чтобы человеку не приходилось додумывать. Общие правила: — имя отвечает на ‘что это?’ и ‘в каких единицах/смысле?’; — чем шире область видимости — тем полнее имя; — запрещены бессмысленные имена: data, info, temp, value, obj, res (кроме очень локального стандарта вроде req/res в express). Переменные: — boolean: is/has/can/should/needs (isEnabled, hasAccess, canRetry); — коллекции: множественное число (users, orders); — индексированные структуры: usersById, ordersByStatus; — единицы измерения: timeoutMs, sizeBytes, ageYears. Функции/методы: — глагол + объект: getUser, buildPayload, parseDate, validateOrder; — предикаты: isValidX, hasX; — обработчики: выбираем один стиль и держим его (handleX или onX). Типы/интерфейсы/классы: — PascalCase; — смысловые алиасы: UserId, OrderStatus; — интерфейсы без префикса I (если нет исторической причины). Разделение домена и транспорта: — домен: User; — транспорт: UserDto; — представление (если есть слой): UserViewModel. 6) ООП: строго, но без зоопарка Наследование допускается только при реальном is-a. Правило: максимум 2 уровня наследования: Base → Derived → Concrete. Третий уровень запрещён. Дальше — композиция. Композиция предпочтительнее: сервисы собираются из зависимостей (Repository/Client/Logger), а не наследуются от ‘BaseEverythingService’. Классы vs функции: — классы: когда есть состояние, инварианты, жизненный цикл; — функции/модули: когда это чистая логика/утилиты. Vue-слой: — компоненты: UI и склейка; — бизнес-логика: composables/services; — доступ к API: отдельный client/service слой. 7) TypeScript-строгость — any запрещён по умолчанию; если очень надо — unknown + runtime-проверка; — предпочитаем union types вместо ‘магических строк’; — enum используем осторожно; на фронте часто лучше string union; — типы должны упрощать чтение: не пишем ‘типовую поэзию’ ради умности. 8) Ошибки и исключения (Node.js) — ошибки не глотаем; — try/catch пишем только там, где можем обработать, или добавляем контекст и пробрасываем дальше; — свои классы ошибок/коды допустимы, но без бесконечного зоопарка. 9) Async/await — не смешиваем then/catch и await в одном модуле без причины; — параллельные операции: Promise.all; — последовательные операции: for..of / for. Запрещено: forEach(async () = ...) — это ловушка, которая не ждёт так, как ожидают. 10) Как мы применяем это в ревью (правила заботы о команде) Ревью — не про ‘поймать на ошибке’, а про качество общего продукта и снижение будущих затрат. Мини-правила: — видим reduce → обязателен вопрос: ‘это реально свёртка в одно значение?’; — видим for → автор обязан указать причину: break/continue, perf, async-seq, аллокации; — видим 5 ранних return в бизнес-логике → просим привести к одному return в конце (кроме валидации); — видим имена data/temp/value → просим переименовать; — видим наследование глубже 2 уровней → блокируем MR. 11) Как решаем спорные моменты Если есть два корректных варианта, по умолчанию выбираем тот, который: — проще прочитать и объяснить; — проще отладить; — проще поддерживать и расширять; — соответствует стандарту проекта. Исключения возможны. Мы не фанатики. Но исключение должно быть полезным для команды и явно объяснённым: ‘вот причина’ и ‘вот эффект’. Не ‘потому что красиво’, а ‘потому что это снижает риск/упрощает поддержку/даёт измеримую выгоду’. Если хочешь, я могу сделать версию 1.1, где добавлю короткие ‘формулировки для ревью’ в одну-две строки (как готовые цитаты) и отдельный раздел ‘структура проекта’ — но мне нужно уточнение: во Vue у вас Pinia или Vuex, а на Node — Express, Nest или Fastify?