Код пишут один раз, а читают десятки. Через полгода его читаете вы сами — без контекста, который был в голове в момент написания, без помнящихся договорённостей и без понимания, почему условие написано именно так. Отсюда и все правила читаемости: они существуют не ради красоты, а ради того, чтобы изменение в проекте стоило часы, а не недели.
Что делает код читаемым
Набор приёмов небольшой и почти не зависит от языка. Мы применяем его и в старых проектах на PHP, и в новых на JavaScript.
- Имена по смыслу. Переменная ordersToShip лучше, чем arr2, а функция calculateDeliveryCost понятнее, чем calc. Длинное точное имя выигрывает у короткого загадочного.
- Короткие функции. Одна задача на функцию — тогда её можно прочитать целиком и удержать в голове.
- Ранний выход. Проверки в начале и return вместо вложенных условий на пять уровней.
- Комментарий про «почему», а не «что». Что делает строка, видно из кода; почему сделано именно так и какое ограничение обходится — нет.
- Единый стиль. Одинаковое оформление во всём проекте: отступы, кавычки, порядок импортов. Спорить о стиле дешевле один раз и зафиксировать в конфиге.
- Явное лучше неявного. Магические числа выносим в константы с именами, скрытые побочные эффекты убираем.
Отдельно про имена булевых значений и функций: isActive, hasAccess, shouldRetry читаются как утверждение, и условие с ними понятно без разбора. Имя flag не говорит ничего.
Признаки, что кусок пора переписать
Мы пользуемся простым списком симптомов. Он не требует метрик и работает при обычном чтении кода.
| Признак | Что обычно за ним стоит | Что делаем |
|---|---|---|
| Функция не помещается на экран | Смешаны несколько задач | Выделяем шаги в отдельные функции с говорящими именами |
| Пять уровней вложенности | Не вынесены проверки, нет раннего выхода | Переносим условия наверх, выходим сразу |
| Копия одного кода в трёх местах | Правку сделают только в одном | Выносим общее, но только после третьего повторения |
| Комментарий объясняет каждую строку | Код непонятен без перевода | Переименовываем переменные, убираем комментарии-подстрочник |
| Длинный список параметров | Функция знает слишком много о вызывающем коде | Собираем параметры в объект или разделяем функцию |
| Страшно менять | Нет тестов и понимания зависимостей | Сначала тесты на текущее поведение, потом правки |
Чего не стоит делать
Читаемость легко превратить в самоцель. Абстракция ради абстракции усложняет не меньше, чем длинная функция: чтобы понять три строки логики, приходится открыть пять файлов и проследить цепочку интерфейсов. Слой, добавленный «на будущее», обычно так и не пригождается, но читать его придётся всем.
- Не выносите общий код после первого совпадения: два похожих места часто расходятся дальше.
- Не заводите настройку под каждый вариант поведения, если вариант один.
- Не сокращайте имена ради экономии символов: место в файле дешевле времени на разбор.
- Не оставляйте закомментированный код. Для истории есть система контроля версий.
Хороший критерий проверки — сможет ли коллега разобраться в вашем модуле за пятнадцать минут без вашей помощи. Если для этого нужна ваша устная лекция, модуль читаемым не является.
Как мы подходим к рефакторингу
Отдельный проект «перепишем всё» почти всегда затягивается и почти никогда не приносит того, что обещал. Мы работаем иначе.
- Улучшаем код там, где он и так меняется по задаче. Трогаем то, что рядом с правкой, а не то, что просто не нравится.
- Отделяем переформатирование от изменения логики. Это разные коммиты, иначе в разборе изменений невозможно найти суть правки среди перенесённых скобок.
- Заводим хотя бы минимальные тесты на затрагиваемое поведение до правки, а не после.
- Меняем небольшими шагами, каждый из которых оставляет проект работающим.
- Фиксируем в задаче, что именно улучшено, чтобы это было видно в отчёте, а не выглядело как самодеятельность.
Такой подход медленнее выглядит и быстрее работает: проект всё время остаётся живым, а улучшения накапливаются вместе с обычными задачами.
Что помогает удерживать качество
Читаемость держится не на дисциплине отдельных людей, а на нескольких договорённостях, которые проверяются автоматически.
| Что настраиваем | Что это даёт команде |
|---|---|
| Линтер и автоформатирование в проекте | Стиль перестаёт быть темой для споров в ревью |
| Проверка на сборке до слияния | Сломанный код не попадает в основную ветку |
| Ревью небольшими изменениями | Правку на 200 строк читают, правку на 2000 пролистывают |
| Тесты на критичные сценарии | Меняющий код перестаёт бояться его трогать |
| Короткий документ о структуре проекта | Новый разработчик понимает, где что лежит, за час |
Важно, что ничего из этого не требует отдельного бюджета и большого внедрения. Линтер и автоформатирование настраиваются за один вечер и дальше работают сами.
Комментарии, коммиты и документация
Три места, где обычно хранится контекст, и все три чаще всего пустые. Полезное распределение выглядит так: в комментарии — причина нестандартного решения и ссылка на задачу; в сообщении коммита — что изменилось и зачем, а не «фиксы»; в коротком файле рядом с проектом — как поднять окружение, где настройки и куда идти за доступами.
Мы просим писать в комментарии именно ограничение: «здесь ждём ответ, потому что внешний сервис не отдаёт статус сразу». Такая строка экономит следующему разработчику полдня раскопок и предотвращает «оптимизацию», которая всё сломает.
Зачем это бизнесу
Читаемый код — это скорость изменений и стоимость смены подрядчика. Проект, в котором новый разработчик разбирается неделю, дешевле в поддержке, чем проект, где на это уходит месяц и всё равно ломается смежная функциональность. Разница видна не в момент сдачи, а на втором-третьем году жизни проекта, когда накапливаются доработки.
- Правка занимает часы, а не дни, потому что понятно, где менять.
- Задачу можно передать другому разработчику без длинной передачи дел.
- Ошибки находятся при чтении кода, а не в продакшене.
- Проект не привязан к одному человеку, который «единственный тут разбирается».
Это же объясняет, почему на аудите чужого кода мы сначала смотрим не на технологии, а на структуру, имена и наличие тестов. Стек можно выучить, а хаос приходится разбирать.
С чего начать в существующем проекте
Не с переписывания. Возьмите один модуль, который чаще всего меняется, и приведите в порядок именно его: имена, длину функций, ранний выход, тесты на основной сценарий. Через несколько задач станет понятно, стоит ли распространять подход дальше, и сколько это занимает времени на практике.
Если поддерживать качество кода внутри некому, помогает выделенную команду разработки подключить к проекту: разработчики работают по вашим задачам, но по своим правилам ревью и тестирования. Напишите нам, какой у вас стек и что болит сильнее всего, и мы предложим состав команды.











