Имя функции и её контракт

Назначение

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

Входные данные

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

Тип параметра: число, строка, указатель, структура
Диапазон: допустимые минимальные и максимальные значения
Единицы: метры, секунды, байты, пиксели
Формат строки: кодировка, разделители, обязательные поля

Результат и побочные эффекты

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

Ошибки

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

Условия сбоев: нехватка памяти, неверный формат, сетевой таймаут
Способ передачи: код, исключение, выходной параметр
Состояние после ошибки: какие данные гарантированно не изменены

Пример

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

Ограничения

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