Согласованность

Соблюдайте порядок параметров, принципы именования и использования

При разработке библиотеки поддерживайте единообразие порядка аргументов, схемы именования и использования перегрузок. Например, если один из существующих методов имеет параметры offset и length, не следует выбирать для нового метода альтернативные варианты, такие как startIndex и endIndex, если для этого нет веской причины.

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

BigDecimal(200)
BigDecimal(200L)
BigDecimal("200")

Не смешивайте такие имена параметров, как startIndex и stopIndex, с синонимами, например beginIndex и endIndex. Аналогично, выберите один термин для значений в коллекциях, например element, item, entry или entity, и придерживайтесь его.

Давайте связанным методам последовательные и предсказуемые имена. Например, в стандартной библиотеке Kotlin есть такие пары, как first и firstOrNull, single или singleOrNull. По этим парам ясно, что одни методы могут возвращать null, а другие — выбрасывать исключение. Объявляйте параметры от общего к частному: сначала указывайте обязательные входные данные, а в конце — необязательные. Например, в функции CharSequence.findAnyOf сначала указывается коллекция strings, затем — startIndex и, наконец, флаг ignoreCase.

Рассмотрим библиотеку для управления данными сотрудников, которая предоставляет следующий API для поиска сотрудников:

fun findStaffBySeniority(
    startIndex: Int, 
    minYearsServiceExclusive: Int
): List<Employee>

fun findStaffByAge(
    minAgeInclusive: Int, 
    startIndex: Int
): List<Employee>

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

Используйте объектно-ориентированный подход для данных и состояния

Kotlin поддерживает как объектно-ориентированный, так и функциональный стили программирования. Используйте классы для представления данных и состояния в API. Если данные и состояние имеют иерархическую структуру, рассмотрите возможность использования наследования.

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

Выбирайте подходящий механизм обработки ошибок

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

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

Рассмотрите возможность предоставить перегруженные версии функций: одна выбрасывает исключение, а другая вместо этого оборачивает его в тип результата. В таких случаях используйте суффикс Catching, чтобы указать, что функция перехватывает исключения. Например, в стандартной библиотеке есть функции run и runCatching, использующие это соглашение. В библиотеке корутин для каналов также есть методы receive и receiveCatching.

Не используйте исключения для обычного управления потоком выполнения. Спроектируйте API так, чтобы можно было проверять условия перед выполнением операций и тем самым избегать ненужной обработки ошибок. Здесь можно применить полезный шаблон разделения команд и запросов.

Соблюдайте соглашения и обеспечивайте качество

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

Используйте автоматизированные инструменты статического анализа (линтеры), чтобы проверять соответствие кода общим соглашениям Kotlin и соглашениям конкретного проекта.

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

Используйте этот набор тестов в процессе разработки, чтобы проверять, что изменения не нарушают существующее поведение. Запускайте тесты при каждом выпуске в рамках стандартизированного конвейера сборки и выпуска. Такие инструменты, как Kover, можно интегрировать в процесс сборки для измерения покрытия и создания отчётов.

Следующий шаг

В следующей части руководства вы узнаете о предсказуемости.

Перейти к следующей части