Имена в коде: почему это важнее, чем кажется

Имена в коде — это названия переменных, функций, файлов, таблиц и полей. Они кажутся мелочью, пока не приходится искать, чем data отличается от data2 и почему handleClick списывает деньги с карты.

Код читают гораздо чаще, чем пишут. Хорошее имя экономит время при каждом чтении, плохое — отнимает. Когда код пишет и читает ИИ, ставки выше: у ассистента нет памяти о проекте, и имена для него — главная подсказка, что где лежит и что делает.

Почему для ИИ это особенно важно

Человек, который полгода работает с проектом, помнит, что process() в файле helpers.ts на самом деле отправляет счёт клиенту. ИИ-ассистент этого не помнит. Он видит название и делает вывод по нему.

Отсюда типичные проблемы вайбкода:

ассистент не находит существующую функцию, потому что она названа не так, как он искал, и пишет новую;
правит не ту функцию из двух похожих;
использует поле status в одном значении, хотя в соседней таблице оно означает другое.

Хорошие имена работают как документация, которую невозможно забыть обновить: она прямо в коде.

Правила для имён в коде, которые работают

Называй по смыслу, а не по типу. users лучше, чем array, unpaidInvoices лучше, чем list. Имя отвечает на вопрос «что это», а не «как это хранится».

Функции — глаголами. sendInvoice, getActiveProjects, cancelSubscription. По имени должно быть понятно, что функция делает, и особенно — меняет ли она что-то. getUser не должен создавать пользователя, если его нет.

Флаги — вопросами. isPaid, hasAccess, canEdit. Тогда условие читается как фраза: if (user.canEdit).

Обработчики событий — по действию, а не по жесту. handleClick ничего не говорит. submitOrder или openPaymentDialog говорят всё.

Единицы измерения в имени. timeoutMs, priceCents, durationDays. Половина ошибок с деньгами и временем — это когда одна часть кода думает в рублях, а другая в копейках.

Одно понятие — одно слово. Если в продукте есть «клиенты», не называй их в одном месте customer, в другом client, в третьем buyer. Выбери слово и держись его везде: в коде, в базе, в интерфейсе для команды.

Без мусорных суффиксов. New, Old, 2, Final, Temp — признак того, что рядом лежит дубль. Если новая версия заменила старую, удали старую и дай новой нормальное имя.

Без свалок. Файлы utils, helpers, common, misc быстро становятся местом, куда кладут всё, чему не нашли дома. Если функция форматирует цену, ей место в pricing или format-price, а не в utils.

Длина имени

Короткое имя хорошо там, где область видимости маленькая: i в цикле из трёх строк никого не путает. Чем дальше имя живёт и чем больше мест его используют, тем подробнее оно должно быть. Функция, которую вызывают из двадцати файлов, заслуживает имени из трёх слов.

Обратная крайность — getAllActiveNonDeletedUsersWithPaidSubscriptionFromDatabase. Если имя не помещается в голове, функция, скорее всего, делает слишком много.

Соглашения о стиле

camelCase, snake_case, PascalCase — выбор между ними обычно уже сделан языком и фреймворком. Следуй тому, что принято в экосистеме, и включи линтер, чтобы за этим не приходилось следить глазами. Главное — единообразие: проект, где половина файлов user-card.tsx, а половина UserCard.tsx, путает и людей, и инструменты.

С базой данных отдельная история: имена таблиц и полей переименовывать дороже всего, потому что за ними миграции, бэкапы и чужие интеграции. Подумай над ними на пять минут дольше.

Как переименовать то, что уже есть

Не надо переименовывать весь проект за раз. Используй рефакторинг «Rename symbol» в редакторе — он меняет имя во всех местах, где оно используется, а не только там, где совпал текст. Переименование — отдельный коммит, без других изменений. Начни с самого вводящего в заблуждение: функции, чьё имя обещает одно, а делает она другое.

И запиши договорённости в инструкции для ИИ-ассистента: какие слова используются для каких понятий, какие суффиксы запрещены. Ассистент следует таким правилам заметно лучше, чем угадывает.

Коротко

Имена в коде — главная подсказка и для людей, и для ИИ, у которого нет памяти о проекте.
Называй по смыслу, функции — глаголами, флаги — вопросами, с единицами измерения в имени.
Одно понятие — одно слово во всём проекте; никаких New, 2 и файлов-свалок utils.
Чем шире используется имя, тем подробнее оно должно быть.
Переименовывай инструментами редактора, отдельными коммитами, начиная с самых обманчивых имён.

Если имена в проекте давно разъехались, SUBXCAT поможет навести в них порядок без остановки разработки.