Типы и тесты как документация

Комментарий заявляет инвариант; тип его кодирует. Документация протухает, потому что нет механизма, поддерживающего её истинной. Комментарий не проверяет ровно никто — ни компилятор, ни CI, ни следующий читатель, скользнувший по нему взглядом. В тот момент, когда код меняется, а комментарий нет, у тебя рядом с работающим кодом сидит уверенная ложь. Тип — иной по природе: он часть программы. Если код противоречит типу, сборка падает. Поэтому вопрос для любого инварианта, который стоит сформулировать, не «стоит ли это закомментировать?», а «могу ли я сделать документацией сам компилятор?»

// rots silently:
// precondition: status is one of 'draft' | 'sent' | 'paid'
function advance(invoice: { status: string }) { /* ... */ }

// cannot rot — the compiler is the doc:
type Status = "draft" | "sent" | "paid";
function advance(invoice: { status: Status }) { /* ... */ }

Строковая версия говорит про три состояния; объединение обеспечивает три состояния. Четвёртое значение — ошибка компиляции, а не рантайм-сюрприз через три деплоя.

Размеченные объединения запрещают недопустимые состояния. Самые дорогие баги — это не неверные значения, а невозможные комбинации, которые тип разрешил: запрос, который одновременно loading: true и имеет data; заказ, который cancelled, но всё ещё имеет shippedAt. Комментарий («не задавай data во время загрузки») — это молитва. Размеченное объединение удаляет недопустимое состояние из типа, так что ни один путь кода не может его сконструировать.

// allows the impossible: loading && data && error all set at once
type Bad = { loading: boolean; data?: User; error?: Error };

// the four real states, and only those:
type Fetch =
  | { tag: "idle" }
  | { tag: "loading" }
  | { tag: "ok"; data: User }
  | { tag: "err"; error: Error };

Теперь data существует только когда tag === "ok". Читатель узнаёт весь конечный автомат из типа, а компилятор отвергает любой обработчик, забывший случай. Тип — это и документация, и проверка на полноту.

Брендированные (непрозрачные) типы документируют единицы и идентичность, останавливая молчаливую путаницу. TypeScript структурен: UserId и OrderId оба — string, поэтому компилятор с радостью позволит передать один туда, где место другому. Классический прод-инцидент ровно про это — функция принимает (userId: string, accountId: string), и кто-то меняет аргументы местами. Бренд придаёт примитиву номинальную идентичность без рантайм-стоимости.

type Brand<T, B> = T & { readonly __brand: B };
type UserId = Brand<string, "UserId">;
type Cents  = Brand<number, "Cents">;

function chargeAccount(user: UserId, amount: Cents) { /* ... */ }
// chargeAccount(orderId, dollars) // ✗ compile error — wrong brand

Бренд — это документация того, что amount в центах, а не в долларах, и что этот string — id пользователя, а не любая строка. Но заметь цену: это окупается только там, где путаница правдоподобна и дорога. Брендировать каждый string — режим отказа из шага 5.

Хорошо названный тест — это исполняемая спецификация; набор тестов — живая документация. Комментарий, описывающий поведение, дрейфует; тест, описывающий поведение, падает, когда поведение дрейфует. Фокус в именовании: тест с именем test('works') ничего не документирует, а test('rejects an amount of zero') — это предложение в спецификации, которое к тому же выполняется. Прочитанные сверху вниз, хорошо названные тесты — самое точное прозаическое описание модуля из существующих, потому что каждая строка проверяется на каждом коммите.

describe("parsePositiveInt", () => {
  it("returns a PositiveInt for a positive integer", () => {
    expect(parsePositiveInt(5)).toEqual({ ok: true, value: 5 });
  });
  it("rejects zero", () => {
    expect(parsePositiveInt(0).ok).toBe(false);
  });
  it("rejects negatives and non-integers", () => {
    expect(parsePositiveInt(-1).ok).toBe(false);
    expect(parsePositiveInt(2.5).ok).toBe(false);
  });
});

Ты можешь прочитать эти три имени и узнать контракт, не читая тело. Это документация, которая ловит дрейф, — комментарий, который умеет выполняться.