Аргументы и побочные эффекты

Стремись к 0–2 аргументам; три считай требующими причины, а 4+ — отсутствующей концепцией. Каждый параметр — это то, что читатель должен держать в голове, передать правильно и в правильном порядке. Ниладический (без аргументов) или монадический (с одним аргументом) вызов тривиален для чтения и тестирования; триадический вызов уже заставляет помнить, какой boolean был validate, а какой — notify. Это не жёсткий потолок — clamp(value, min, max) — отличная, связная триада. Эвристика — это порог запаха: при четырёх аргументах спроси, какую концепцию место вызова каждый раз пересобирает руками.

// 5 позиционных аргументов: зависят от порядка, нечитаемы в месте вызова
createOrder(customerId, items, 'express', true, null);
//                              ^ shipping  ^ gift  ^ coupon — где что?

Когда несколько параметров всегда путешествуют вместе, это не пять входов — это одна идея (запрос заказа), которую ещё не назвали.

Сверни длинный, связанный список параметров в объект-параметр. Когда параметры группируются — (x, y, width, height), (street, city, zip, country), пять полей заказа выше — введи тип, который называет эту группу. Место вызова становится самодокументируемым, потому что каждое значение помечено, порядок перестаёт иметь значение, а добавление шестого поля — это изменение типа, а не позиционного списка в каждом месте вызова.

interface OrderRequest {
  customerId: string;
  items: LineItem[];
  shipping: ShippingSpeed;
  gift: boolean;
  coupon?: string;
}

createOrder(req: OrderRequest): Order { /* ... */ }

// место вызова: помечено, без порядка, расширяемо
createOrder({ customerId, items, shipping: 'express', gift: true });

Выигрыш условный: он засчитывается только когда поля — настоящая концепция. Сложить несвязанные параметры в мешок не даёт ничего — см. вставку с ошибкой.

Булев флаговый аргумент почти всегда означает, что функция делает две вещи — разбей её. render(item, isAdmin) или save(user, true /* sendEmail */) читается так: в теле есть if (flag), который выбирает между двумя поведениями. Это две обязанности, делящие одно имя, а место вызова save(user, true) нечитаемо, пока не выследишь параметр. Лекарство — сделать два поведения двумя именованными функциями.

// до: одна функция, скрытая развилка, непрозрачное место вызова
function save(user: User, sendEmail: boolean) {
  db.write(user);
  if (sendEmail) mailer.welcome(user);
}
save(user, true);  // true... что есть true?

// после: каждое поведение названо; намерение видно в месте вызова
function saveUser(user: User) { db.write(user); }
function registerUser(user: User) { saveUser(user); mailer.welcome(user); }
registerUser(user);  // читается как есть

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

Не возвращай результаты через аргументы — возвращай их. Выходной аргумент — это параметр, который функция мутирует, чтобы вызывающий мог прочитать результат обратно. Он переворачивает естественное направление чтения: аргументы должны быть входами, поэтому appendFooter(report) выглядит так, будто потребляет report, тогда как на деле она правит его на месте. Читателю приходится знать тело, чтобы понять, кто владеет мутацией.

// выходной аргумент: report идёт ВНУТРЬ, возвращается изменённым — неожиданно
function addTotals(report: Report): void {
  report.total = report.lines.reduce((s, l) => s + l.amount, 0);
}

// разделение команд и запросов: запрос возвращает, эффект команды — в её имени
function totalFor(lines: Line[]): number {
  return lines.reduce((s, l) => s + l.amount, 0);
}
const report = { ...draft, total: totalFor(draft.lines) };

Если функция что-то вычисляет — верни это. Мутация аргумента прячет эффект за параметром, который выглядел как обычный вход.

Делай побочные эффекты явными и именованными; «выглядящая чистой» функция, которая втайне мутирует мир, — самая дорогая ложь, какую говорит сигнатура. Имя вроде parseConfig(text) обещает чистое преобразование: текст на входе, конфиг на выходе, без I/O. Если она ещё и пишет файл или делает сетевой вызов, каждый вызывающий наследует эффект, о котором не просил — тестам нужна реальная инфраструктура, ретраи дублируют запись, а рассуждение о программе ломается. Правило — разделение команд и запросов: функция либо отвечает на вопрос (запрос, чистая, возвращает значение), либо меняет мир (команда, возвращает void/эффект) — и её имя говорит, что именно.

// ЛОЖЬ: чисто выглядящее имя, скрытая запись
function parseConfig(text: string): Config {
  const cfg = JSON.parse(text);
  fs.writeFileSync('/var/cache/config.json', text); // сюрприз — побочный эффект!
  return cfg;
}

// ЧЕСТНО: запрос чист; команда называет свой эффект
function parseConfig(text: string): Config { return JSON.parse(text); }
function cacheConfig(text: string): void { fs.writeFileSync('/var/cache/config.json', text); }

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