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

> Имена в коде решают, поймёт ли проект человек и ИИ-ассистент. Почему плохие названия дорого стоят и какие простые правила именования работают на практике.

Published: 2025-11-08 · Source: https://subxcat.com/ru/articles/naming-in-code · Author: SUBXCAT

Имена в коде — это названия переменных, функций, файлов, таблиц и полей. Они кажутся мелочью, пока не приходится искать, чем `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 поможет навести в них порядок без остановки разработки.