Ответ.

Пакеты, импорты и file-level объявления лежат в основе структуры любого проекта на Kotlin, и разработчики часто сталкиваются с вопросами организации пространства имён и видимости функций.

История вопроса: Kotlin, продолжая традиции Java, поддерживает систему пакетов, однако добавляет концепцию file-level объявлений, что позволяет создавать функции и свойства вне класса, улучшая модульность и выразительность кода.

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

Решение:

Для любого файла может быть явно объявлен package (совпадают с файловой структурой, но могут не совпадать строго)
В одном файле можно разместить несколько классов, top-level функции и свойства, а также object-объявления
Импортировать можно как отдельные члены, так и группы с помощью * или alias

Пример кода:

package utils

import kotlin.math.*
import model.User as UserModel

fun sum(a: Int, b: Int) = a + b

val PI2 = PI * 2

Ключевые особенности:

Top-level объекты и функции доступны по package, не требуют создания инстансов класса
Импорты можно давать alias, что помогает избежать конфликтов имён
Можно импортировать функции, свойства и object-объекты

Вопросы с подвохом.

Могут ли разные файлы с одним именем package содержать объявления с одними и теми же именами функций/свойств?

Да, но приведёт к конфликту имён при компиляции, если не использовать разные имена или alias для импортов. File-level объявления работают в рамках package.

Обязательно ли структура каталогов проекта должна повторять package, как в Java?

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

Можно ли объявлять несколько package внутри одного .kt файла?

Нет, в одном .kt файле можно объявить только один package. Перемешивание package приводит к ошибке компиляции.

Типовые ошибки и анти-паттерны

Несоблюдение единого соглашения о нейминге и структуре пакет/каталог
Кладут очень много разных тематик в один файл, мешают бизнес-логику и утилитарные функции
Использование *-импорта во всех файлах вместо импортов по необходимости — снижает читаемость, может привести к конфликтам

Пример из жизни

Негативный кейс

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

Плюсы:

Легко найти все утилиты в одном месте

Минусы:

Сильно разрастается файл, теряется контекст функций, сложнее поддерживать, затруднён рефакторинг

Позитивный кейс

Строго следуют соглашениям: каждый пакет отражает доменную область, используется file-level только для функций, не принадлежащих какому-либо классу, alias используются для устранения дублирования, каждый файл для своей тематики: