Публичные API и структура

Хорошую библиотеку оценивают по ее внешнему интерфейсу. Решение о том, что сделать доступным, определяет удобство использования Вашего API. 🚪

Функции и типы, которые должен вызывать другой код, образуют Ваш публичный API. Это обещание, которое Вы даете пользователям.

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

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

Файл __init__.mojo пакета может импортировать ключевые имена, чтобы пользователи обращались к ним напрямую через пакет, а не через глубокие пути к файлам.

Собирая импорты в __init__, Вы даете вызывающему коду одну ясную точку входа вместо длинных и хрупких путей к модулям.

Пользователи импортируют из пакета, а не из его файлов. Это позволяет перестраивать внутренние модули, не ломая их код.

Публичные имена должны быть понятны сами по себе. Ясное и стабильное имя — часть соглашения, которое не следует менять.

Добавляйте строку документации к каждой публичной функции и типу. Хорошая документация объясняет вызывающему коду, как правильно использовать API.

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

Сначала представьте, как вызывающий код хочет использовать библиотеку, а затем создайте внутреннюю реализацию для такого удобного взаимодействия. 🎨

Открывайте небольшой и понятный публичный API, повторно экспортируйте ключевые имена в __init__, скрывайте внутренние детали и документируйте предоставляемые возможности. 🎯