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

Интерфейс больше, чем сигнатура

Interface beyond the signature

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

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

Риск: если правило не названо, вызывающий код угадывает.

Зачем это вам

AI-агент часто видит функцию и считает, что понял интерфейс: параметры есть, тип результата есть, можно вызывать. Но настоящая сложность часто спрятана рядом: какие значения допустимы, когда вернется ошибка, можно ли вызывать повторно, что будет с пустыми данными.

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

Суть

Сигнатура (signature) - это видимая форма: имя, параметры, тип результата. Она отвечает на вопрос “как вызвать?”.

Интерфейс (interface) шире. Он отвечает: какие значения допустимы, что модуль обещает вернуть, какие ошибки возможны, какие побочные эффекты есть, какой порядок вызовов нужен.

Контракт (contract) делает ожидания явными. Чем меньше вызывающий код должен угадывать, тем меньше когнитивная нагрузка и тем ниже риск случайных зависимостей.

Аналогия

Сигнатура похожа на кнопку “заказать”. Интерфейс - это еще правила доставки: куда привезут, когда, что делать при ошибке оплаты, можно ли отменить заказ и какие данные нужны.

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

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

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

«Я вынес это в функцию»
Проверьте, появился ли контракт или только новое имя для старого куска кода.
«Нужно обработать edge cases»
Агент говорит о части интерфейса: пустые значения, неверный формат, повторный вызов, недоступный ресурс.
«Добавлю типы»
Типы помогают, но не заменяют правила использования, ошибки и смысловые ограничения.

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

Signature
Сигнатура: имя, параметры и тип результата.
Contract
Контракт: полное обещание модуля перед внешним кодом.

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

Что лучше всего показывает, что интерфейс описан полностью?

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

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