Блок 2 · Урок 3 из 4 · ≈ 9 минут · цель: находить скрытые правила использования

Неформальный интерфейс

Informal interface

Главная мысль: часть интерфейса невозможно увидеть в сигнатуре, но именно она часто ломает дизайн.

Скрытое правило: “сначала вызови A, потом B”.

Цель: превратить догадки в явные правила.

Зачем это вам

Агент может корректно вызвать функцию по типам и всё равно ошибиться, если важное правило живет только в голове автора: “вызывать только после загрузки профиля”, “не передавать архивные записи”, “после сохранения обязательно сбросить кэш”.

Такие правила - часть интерфейса. Если их не назвать, они становятся ловушками для человека, агента и будущих тестов.

Суть

Неформальный интерфейс (informal interface) - это правила, которые нужны для правильного использования, но не выражены прямо в сигнатуре.

К нему относятся инварианты, допустимые состояния, порядок вызовов, побочные эффекты, требования к производительности, ожидания по безопасности и правила восстановления после ошибок.

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

Аналогия

Представьте прибор с одной кнопкой. Формально интерфейс прост: нажать кнопку. Но если кнопку нельзя нажимать мокрыми руками, дольше трех секунд или до прогрева прибора, настоящий интерфейс уже намного шире.

Запомните одно

Если для правильного использования модуля нужно знать правило, это правило уже является частью интерфейса, даже если оно нигде не написано.

Фраза агента → что он имеет в виду

«Тут есть precondition»
Перед вызовом должно быть выполнено условие: состояние, формат данных или порядок действий.
«Есть side effect»
Вызов меняет что-то кроме возвращаемого результата: кэш, базу, очередь, лог, внешнее состояние.
«Нужно задокументировать invariant»
Есть условие, которое должно оставаться истинным после операций модуля.

Мини-словарь

Precondition
Предусловие: что должно быть верно до вызова.
Side effect
Побочный эффект: изменение внешнего состояния помимо возвращаемого результата.
Invariant
Инвариант: условие, которое должно оставаться истинным.

Проверьте себя

Что является частью неформального интерфейса?

Связанные материалы

Основной источник