Согласованность и область видимости

Одно слово на одну концепцию — синонимы это скрытая связанность. Выбери ровно один глагол для операции и одно существительное для доменной сущности, а затем используй их везде. Если «получить пользователя» это getUser, то это getUser в репозитории, в сервисе, в контроллере и в тесте — никогда не fetchUser здесь и retrieveUser там. То же касается существительных: если домен называет сущность Customer, то это Customer от начала и до конца, а не User в аутентификации, Customer в биллинге и Account в дашборде.

// Inconsistent vocabulary — three words, one concept
const a = await userRepo.fetchUser(id);
const b = await userService.getUser(id);
const c = await cache.retrieveUserById(id);

Читатель, пробегающий это глазами, не может предположить, что fetch, get и retrieve взаимозаменяемы — разные слова сигнализируют о разном поведении. Поэтому ему приходится открыть каждое, чтобы подтвердить: «всё это просто чтение по ключу». Этот шаг подтверждения — чистые потери, и они растут с каждым синонимом, который ты вводишь.

Общий словарь — это низкая связанность; расщеплённый словарь — это конкретность смысла. Когда User, Customer и Account обозначают одно и то же, каждый читатель и каждый инструмент рефакторинга обязан держать в голове соответствие User ≡ Customer ≡ Account. Это общее понимание — невидимая зависимость между модулями: измени, что значит Customer в биллинге, и ты молча изменил допущение, на которое опирается модуль аутентификации, потому что они были «одним и тем же» лишь по договорённости, а не по типу.

// Three names, one entity → an unwritten contract readers must memorise
function authenticate(user: User): Session { /* ... */ }
function chargeCard(customer: Customer): Receipt { /* ... */ }
function renderHeader(account: Account): Html { /* ... */ }

Один единый термин (скажем, Customer повсюду) схлопывает три ментальные модели в одну и позволяет системе типов обеспечивать связь вместо памяти читателя. Именно поэтому предметно-ориентированное проектирование продвигает единый язык: общие слова — это самое дешёвое снижение связанности, какое можно купить.

Длина имени должна масштабироваться под область видимости. Правильная длина имени — это функция от того, как далеко оно путешествует и сколько контекста у читателя уже есть. В трёхстрочном цикле читатель видит всё время жизни i одним взглядом, поэтому i не просто приемлемо — более длинное имя здесь это шум, скрывающий форму цикла. На другом полюсе экспортируемая функция путешествует к местам вызова, у которых нет ничего из контекста этого файла, поэтому её имя должно нести смысл само по себе.

// Tiny scope: i and x are perfect — the whole story fits in the eye
for (let i = 0; i < points.length; i++) {
  const x = points[i].x;
  sum += x;
}

// Wide scope: the export must explain itself with zero local context
export function totalRevenueForFiscalQuarter(orders: Order[]): Money { /* ... */ }

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

У каждого правила есть режим отказа — слепое применение делает код хуже. Согласованность и описательность — это силы, а не абсолюты, и чрезмерное применение любой из них — настоящий запах.

• Навязывание длинных имён в крошечных областях добавляет шум. for (let currentIterationIndex = 0; ...) или const userObjectFromArray = points[currentIterationIndex] погребают тривиальный цикл под церемонией. Теперь читателю приходится разбирать длинные идентификаторы, чтобы восстановить структуру, которую i и x показали мгновенно.
• Навязывание лаконичных имён в широких областях скрывает намерение. Экспортируемая function calc(d: Data): R ничего не говорит далёкому вызывающему — ему придётся открыть её, чтобы узнать, что она вычисляет, а это ровно та цена, которую описательные имена существуют, чтобы устранить.
• Навязывание ложной согласованности связывает несвязанные вещи. Если две операции действительно различаются — fetchUser делает сетевой вызов с ретраями, а getUser это чистое чтение из кэша, — схлопывание их в одно слово стирает различие, нужное читателю. Согласованность означает одно слово на одну концепцию, а не одно слово независимо от концепции.

// Over-descriptive local: ceremony obscures a 3-line loop
for (let currentIndexInLoop = 0; currentIndexInLoop < items.length; currentIndexInLoop++) { /* ... */ }

// Under-descriptive export: terse where the reader has no context
export function proc(o: Order[]): number { /* ... */ }

Senior-приём — сначала прочитать область видимости, а затем выбрать длину и слово — никогда не применять «всегда будь описательным» или «всегда переиспользуй тот же глагол» механически.