1. The src folder — where your code lives
If a Kotlin project were a house, then the src folder (from the word source) is the cozy living room where all the main residents gather. This is exactly where all source files with code go—not in the project root, not in the settings folder, and not on the desktop (even if you really want to).
Why separate sources from everything else?
- The
srcfolder contains only the files you write by hand: .kt. - Everything that appears during the build process (compiled .class files that the JVM reads) is placed into other folders like out, build, etc.
- This makes navigation easier, keeps the project cleaner, and makes the IDE happier.
Example structure of a simple project:
MyFirstProject/
├── .idea/ # IntelliJ IDEA service files; don't touch
├── out/ # compiled .class files appear here
├── src/ # this is where your source code lives!
│ └── Main.kt
├── MyFirstProject.iml
└── README.md
src folder. Don’t put images, music, or secret recipes there—other folders exist for that.
2. Packages package
When your code outgrows a single Main.kt file, in Kotlin it’s common to group files into “packages”—like folders in a file system, but for code. Packages help you:
- Avoid name conflicts. If a project has two different
calculate()functions, but they are in different packages, they won’t interfere with each other. - Structure code logically. For example,
com.kotlin.lesson05,com.kotlin.utils.
Package declaration syntax
On the very first line of each Kotlin file, you write:
package com.kotlin.lesson05
This means: everything in this file belongs to the com.kotlin.lesson05 package.
An important best-practice rule:
Unlike Java, the Kotlin compiler allows you to put a file with the com.kotlin package directly in the root of the src folder. But this is strongly not recommended! The official Kotlin Style Guide requires that the folder structure on disk strictly matches the package name. That is, the path to the file should be:
src/com/kotlin/lesson05/Main.kt
How to create a package in IntelliJ IDEA
- In the Project tool window, right-click the
srcfolder. - Select New → Package.
- Enter a name, for example: com.kotlin.lesson05 (the IDE will create the required nested folders).
- Now create a new file inside this package: right-click the com.kotlin.lesson05 folder → New → Kotlin Class/File → enter a name, for example,
Utils.
Example:
src/
└── com/
└── kotlin/
└── lesson05/
└── Utils.kt
Pay attention to the path to your file in the bottom panel. Remember that when creating the project we checked Use compact project structure? This is how it works.
If you turn off compact mode, there will be empty folders.
Why can’t you just dump everything into src?
If you put all files together in one place, the project will quickly turn into a “dump,” where finding the needed function will be harder than finding a laptop charger in a student dorm. Use packages—this makes it easier to navigate the project.
3. Fully qualified name
Every function or tool from the Kotlin standard library also lives in its own package. For example:
- The math function for finding the maximum max() is in the kotlin.math package. Its fully qualified name is kotlin.math.max.
- The random number generator Random is in kotlin.random. The fully qualified name is kotlin.random.Random.
So, fully qualified name = package name + dot + function/class name.
Let’s try using this in code to find the maximum of two numbers:
fun main() {
val a = 10
val b = 20
val maximum = kotlin.math.max(a, b)
println("Maximum number: $maximum")
}
Here we explicitly write kotlin.math.max. The compiler understands exactly which function we are calling.
4. The import operator
Writing the full long name every time is terribly inconvenient. That’s exactly why Kotlin has the import operator.
If we write at the very top of the file, right below package:
import kotlin.math.max
This means: “In this program I will use the max function from the kotlin.math package.” After that, we can write short and clean:
val maximum = max(10, 20)
Regular import
We specify the exact tool we want to use:
import kotlin.math.max
import kotlin.random.Random
Import an entire package *
Sometimes we need many math functions at once. Then we can write an asterisk:
import kotlin.math.*
This means: “Allow using EVERYTHING from the kotlin.math package without the fully qualified name.”
Default Imports
You’ve probably wondered: “Wait, but we already used println(), readln(), and the String type without any imports! How did that work?”
The thing is, Kotlin takes care of you. In every file, it “invisibly” adds so-called default imports. Packages like kotlin.*, kotlin.io.* where I/O functions live, and kotlin.collections.* are imported by default. That’s why the most common commands are available to you right “out of the box.”
5. Classpath — how the JVM finds your code
Classpath is the “route” the Java Virtual Machine (JVM) uses to look for your compiled programs before running them. You can think of it as a list of folders where the JVM will search for the required .class files (which Kotlin turned your code into).
By default, IntelliJ IDEA does everything for you. It automatically adds the folder with compiled code, for example out/production/ProjectName, to the classpath. That is, if you wrote code in the com.kotlin.lesson05 package, IDEA will explain to the virtual machine where to find it.
You don’t need to configure it manually yet, but if you see a strange console error like "ClassNotFoundException", know that the problem is somewhere in the build paths.
6. Organizing code in a project
In Kotlin, there is no “one class = one file” rule
If you’ve ever heard about Java, then you know its strict rule: the name of a public class must match the file name. In Kotlin, it’s much more convenient to program: a single file can contain as many functions or classes as you want.
Kotlin’s main rule is logical grouping. If you have functions for math, put them in a MathUtils.kt file.
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
}
The file name should be meaningful. Names like aaa.kt or Test2.kt will be tolerated by IDEA, but you’ll confuse yourself with them after a couple of days.
Where to store resources (images, text files)?
- If your program needs to read text from an external file, a separate folder is usually created for resources in the project root, for example resources or data.
- In IntelliJ IDEA, you can tell the project this is an important folder: right-click the folder → Mark Directory as → Resources Root.
Example of a correct structure:
MyFirstProject/
├── src/
│ └── com/kotlin/lesson05/
│ └── Main.kt
├── resources/
│ └── config.txt
7. Common mistakes when working with project structure
The word package is not on the first line
In Kotlin, the package declaration must be the first meaningful line in the file (comments before it are allowed, but code or imports are not). If you write imports and then the package, the compiler will produce an error.
Folder structure doesn’t match the package
If the beginning of the file says package com.kotlin.lesson05, but the file is physically located directly in src, IDEA will underline the package name in yellow, warning about the mismatch. Remember the best-practice rule: folders should reflect packages!
Manually moving files via Windows/macOS File Explorer
If you moved a .kt file to another folder using a regular file manager on your computer, the package line inside the file will not update automatically, and the project will break. Do moves (Drag and Drop) only inside the Project window in IntelliJ IDEA—the smart IDE will update all packages and paths itself!
GO TO FULL VERSION