Обзор минимизации когнитивной сложности

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

Стратегии минимизации когнитивной сложности включают:

• Простота: Стремитесь к тому, чтобы API предоставлял максимум возможностей при минимальном количестве компонентов, повторно используя существующие типы и структуры Kotlin, чтобы избежать избыточности. По возможности создавайте небольшой набор базовых абстракций и выстраивайте на их основе дополнительные возможности.

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

• Последовательность: Придерживайтесь единого и ясного подхода ко всем аспектам проектирования API. Используйте единообразные соглашения об именовании, стратегии обработки ошибок и шаблоны — как объектно-ориентированные, так и функциональные.

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

• Удобство отладки: Убедитесь, что библиотека помогает пользователям устранять неполадки, упрощая извлечение информации и навигацию по вложенным вызовам функций. При возникновении исключений их тип и содержимое должны соответствовать исходной проблеме и предоставлять все необходимые сведения для эффективной диагностики и решения. Должна быть возможность фиксировать и выводить состояние объектов предметной области, а также просматривать любые промежуточные представления.

• Тестируемость: Убедитесь, что и библиотеку, и использующий её код можно легко тестировать.

В следующих разделах подробнее рассказывается о реализации этих стратегий на Kotlin.