Введение в рекомендации для авторов библиотек

Это руководство содержит краткий обзор лучших практик и идей, которые следует учитывать при разработке библиотек.

Чтобы быть эффективной, библиотека должна достигать определённых фундаментальных целей. В частности, она должна:

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

• Соответствовать нефункциональным критериям, подходящим для предметной области. Обычно к ним относятся производительность, надёжность, безопасность и удобство использования. Относительная важность этих критериев может сильно различаться. Например, для библиотеки, предназначенной для пакетной обработки, может не требоваться такой же уровень производительности, как для библиотеки, используемой в высокочастотной торговле.

Основная цель этого руководства — рассмотреть характеристики, которыми должна обладать библиотека, чтобы оставаться востребованной и популярной среди пользователей. К ним относятся:

• Снижайте когнитивную сложность: Все разработчики должны заботиться о читабельности и удобстве сопровождения своего кода. Крайне важно уменьшать умственные усилия, необходимые другим разработчикам для чтения, понимания и использования ваших API. Для этого создавайте ясные, согласованные, предсказуемые и удобные для отладки библиотеки.

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

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

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

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