Структура Kotlin-проєкту: src, package, імпорти та classpath

1. Папка src — де «живе» ваш код

Якби Kotlin-проєкт був будинком, то папка src (від слова source) — це затишна вітальня, де збираються всі головні мешканці. Саме сюди потрапляють усі вихідні файли з кодом. Не в корінь проєкту, не в папку з налаштуваннями й не на робочий стіл (навіть якщо дуже хочеться).

Чому варто відокремлювати вихідні файли від усього іншого?

• У папці src зберігаються лише файли, які ви пишете вручну: .kt.
• Усе, що зʼявляється під час збирання (скомпільовані .class-файли, які читає віртуальна машина JVM), потрапляє в інші папки: out, build тощо.
• Так простіше орієнтуватися в проєкті: він виглядає охайніше, а IDE працює стабільніше.

Приклад структури простого проєкту:

MyFirstProject/
├── .idea/           # службові файли IntelliJ IDEA, не чіпаємо
├── out/             # тут зʼявляються скомпільовані .class-файли
├── src/             # ось тут «живе» ваш вихідний код!
│   └── Main.kt
├── MyFirstProject.iml
└── README.md

2. Пакети package

Коли ваш код переростає один файл Main.kt, у Kotlin прийнято групувати файли за «пакетами». Це як папки у файловій системі, тільки для коду. Пакети допомагають:

• Уникати конфліктів імен. Якщо в проєкті є дві різні функції calculate(), але вони лежать у різних пакетах, то не заважатимуть одна одній.
• Логічно структурувати код. Наприклад: com.kotlin.lesson05, com.kotlin.utils.

Синтаксис оголошення пакета

У першому рядку кожного Kotlin-файлу пишуть:

package com.kotlin.lesson05

Це означає: увесь вміст цього файла належить пакету com.kotlin.lesson05.

Важливе правило гарного тону:
На відміну від Java, компілятор Kotlin дозволяє покласти файл із пакетом com.kotlin прямо в корінь папки src. Але робити так наполегливо не радять! Офіційний Kotlin Style Guide вимагає, щоб структура папок на диску суворо збігалася з імʼям пакета. Тобто шлях до файла має бути таким:

src/com/kotlin/lesson05/Main.kt

Як створити пакет в IntelliJ IDEA

1. У панелі проєкту клацніть правою кнопкою миші на папці src.
2. Виберіть New → Package.
3. Введіть імʼя, наприклад: com.kotlin.lesson05 (IDE сама створить потрібні вкладені папки).
4. Тепер створіть новий файл усередині цього пакета: клацніть правою кнопкою миші на папці com.kotlin.lesson05 → New → Kotlin Class/File → введіть імʼя, наприклад Utils.

Приклад:

src/
└── com/
    └── kotlin/
        └── lesson05/
            └── Utils.kt

Зверніть увагу на шлях до вашого файла в нижній панелі. Памʼятаєте, під час створення проєкту ми поставили позначку Use compact project structure? Ось як вона працює.

Якщо вимкнути компактний режим, зʼявляться порожні папки.

Чому не можна просто складати все в src?

Якщо складати всі файли впереміш, проєкт швидко перетвориться на «звалище». Тоді знайти потрібну функцію буде складніше, ніж відшукати зарядний пристрій для ноутбука в студентському гуртожитку. Користуйтеся пакетами — так буде значно легше орієнтуватися в проєкті.

3. Повне імʼя

Кожна функція або інструмент зі стандартної бібліотеки Kotlin також має свій пакет. Наприклад:

• Математична функція для пошуку максимуму max() лежить у пакеті kotlin.math. Її повне імʼя — kotlin.math.max.
• Генератор випадкових чисел Random лежить у kotlin.random. Повне імʼя — kotlin.random.Random.

Тобто повне імʼя = імʼя пакета + крапка + імʼя функції/класу.

Спробуймо застосувати це в коді та знайти максимум із двох чисел:

fun main() {
    val a = 10
    val b = 20
    val maximum = kotlin.math.max(a, b)
    println("Найбільше число: $maximum")
}

Тут ми явно пишемо kotlin.math.max. Компілятор точно розуміє, яку саме функцію ми викликаємо.

4. Оператор import

Щоразу писати повне довге імʼя — дуже незручно. Саме для цього в Kotlin існує оператор import (імпорт).

Якщо ми пишемо на самому початку файла, одразу під package:

import kotlin.math.max

Це означає: «У цій програмі я буду використовувати функцію max з пакета kotlin.math». Після цього можна писати коротко й охайно:

val maximum = max(10, 20)

Звичайний import

Ми вказуємо конкретний інструмент, який хочемо використовувати:

import kotlin.math.max
import kotlin.random.Random

Імпорт усього пакета *

Іноді нам потрібно одразу багато математичних функцій. Тоді можна поставити зірочку:

import kotlin.math.*

Це означає: «Дозволити використовувати все з пакета kotlin.math без повного імені».

Імпорти за замовчуванням

Ви напевно поставили собі запитання: «Зачекайте, але ми ж уже користувалися println(), readln() і типом String без жодних імпортів! Як це працювало?»

Річ у тім, що Kotlin «піклується» про вас. У кожен ваш файл мова «невидимо» додає так звані базові імпорти. Пакети kotlin.*, kotlin.io.* (де «живуть» функції введення-виведення), kotlin.collections.* імпортуються за замовчуванням. Тому найуживаніші команди доступні вам одразу «з коробки».

5. Classpath — як JVM шукає ваш код

Classpath — це «маршрут», за яким віртуальна машина Java (JVM) шукає ваші скомпільовані програми перед запуском. Це можна уявити як список папок, у яких JVM шукатиме потрібні .class-файли (на які Kotlin перетворив ваш код).

За замовчуванням IntelliJ IDEA все робить за вас. Вона сама додає папку зі скомпільованим кодом, наприклад out/production/ProjectName, у classpath. Тобто якщо ви написали код у пакеті com.kotlin.lesson05, IDEA сама «пояснить» віртуальній машині, де його знайти.

Поки що вам не потрібно налаштовувати це вручну. Але якщо в консолі зʼявиться дивна помилка на кшталт «ClassNotFoundException», майте на увазі: проблема десь у шляхах збирання.

6. Організація коду в проєкті

У Kotlin немає правила «Один клас = один файл»

Якщо ви колись чули про Java, то знаєте її жорстке правило: імʼя публічного класу зобовʼязане збігатися з імʼям файла. У Kotlin програмувати набагато зручніше: в одному файлі може бути скільки завгодно функцій або класів.

Головне правило Kotlin — логічне групування. Якщо у вас є функції для математики, зберігайте їх у файлі MathUtils.kt.

src/com/kotlin/lesson05/MathUtils.kt

package com.kotlin.lesson05

fun calculateSum(a: Int, b: Int): Int {
    return a + b
}

fun calculateDifference(a: Int, b: Int): Int {
    return a - b
}

Файл має називатися змістовно. Назви на кшталт aaa.kt або Test2.kt IDEA стерпить, але ви самі заплутаєтеся в них уже за кілька днів.

Де зберігати ресурси (зображення, текстові файли)?

• Якщо вашій програмі потрібно читати текст зі стороннього файла, для ресурсів зазвичай створюють окрему папку в корені проєкту, наприклад resources або data.
• В IntelliJ IDEA можна повідомити проєкту, що це важлива папка: клацніть правою кнопкою миші на папці → Mark Directory as → Resources Root.

Приклад правильної структури:

MyFirstProject/
├── src/
│   └── com/kotlin/lesson05/
│       └── Main.kt
├── resources/
│   └── config.txt

7. Типові помилки під час роботи зі структурою проєкту

Слово package написано не в першому рядку
У Kotlin оголошення пакета package має бути першим значущим рядком у файлі (коментарі перед ним писати можна, а от код чи імпорти — ні). Якщо ви напишете імпорти, а під ними — пакет, компілятор видасть помилку.

Невідповідність структури папок і пакета
Якщо на початку файла написано package com.kotlin.lesson05, а сам файл фізично лежить просто в src, IDEA підкреслить назву пакета жовтим, попереджаючи про невідповідність. Памʼятайте про правила гарного тону: папки мають відповідати пакетам!

Ручне переміщення файлів через провідник Windows/macOS
Якщо ви перемістили файл .kt в іншу папку через звичайний провідник на компʼютері, рядок package усередині файла сам не оновиться — і проєкт зламається. Переміщуйте файли (Drag and Drop) лише всередині вікна Project в IntelliJ IDEA: середовище саме оновить усі пакети та шляхи.