skip to content

Must a Kotlin file's name match the names of the classes it declares? What are the practical conventions?

level: middleimportance: should knowfreq 49%

answer

  1. No compiler rule linking file name to class name
  2. Many classes or none per file allowed
  3. Single-class file: name file after the class
  4. Utility file: name after its content
  5. Convention, not enforcement

basics

~20 s

No. A Kotlin file can be named anything and can hold zero, one, or many classes with different names. By convention, if a file has one main class you usually name the file after it.

solid answer

~40 s

Kotlin has no rule tying the file name to any declared class name - unlike Java, where a public class must live in a file of the same name. A .kt file may declare several classes, none matching the file, or none at all (just functions/properties). The official Kotlin style guide recommends: if a file contains a single class (possibly with related top-level members), name the file after that class using UpperCamelCase + .kt; if it holds only top-level functions/typealiases, name it descriptively for its content (e.g. Collections.kt, MathUtils.kt). Files with multiple unrelated classes are discouraged for readability. The compiler enforces none of this; it is purely convention plus the generated facade naming (MathUtilsKt) that benefits from a meaningful file name.

go deeper

for a junior

Knows the file name need not match the class and there is no Java-style restriction.

for a middle

States both the absence of a compiler rule and the style-guide naming conventions for single vs multi-declaration files.

for a senior

Designs file layout for discoverability (one primary type, related extensions/typealiases) and explains facade-name impact.

for a principal

Sets team-wide file-organization standards balancing navigation, review diffs, and stable Java-facing facade names.

## The hard rule: there is none The Kotlin compiler does **not** require the file name to match any class. These are all legal: ```kotlin // File: shapes.kt class Circle class Square fun area(c: Circle): Double = 0.0 // no class named 'shapes' anywhere ``` Contrast with Java, where a `public class Circle` must be in `Circle.java`. ## Why the freedom is useful - Group small, tightly related types together (e.g. a sealed hierarchy: `sealed interface Result`, `class Ok`, `class Err` in `Result.kt`). - Keep a class plus its extension functions and a `typealias` in one file. - Hold a pure utility file of top-level functions with no class at all. ## The conventions (Kotlin style guide) - **Single class file**: name the file exactly like the class, UpperCamelCase, e.g. `OrderService.kt` for `class OrderService`. - **Top-level-only file**: name it after what the functions describe, e.g. `StringExtensions.kt`, `MathUtils.kt`. - **Multiple related types**: a meaningful umbrella name (e.g. `Events.kt` for several event classes) - but avoid dumping many unrelated classes in one file; it hurts navigation. ## Interaction with the JVM facade Because top-level members compile into a `<FileName>Kt` facade, a clear file name yields a clear facade name (`MathUtilsKt`), improving stack traces and Java interop readability. You can still override it with `@file:JvmName`. ## Practical takeaway The language gives flexibility; the team's style guide and IDE conventions (IntelliJ offers to rename file/class together) give discipline. Prefer one primary public type per file for discoverability, even though the compiler permits more.

  • If a file declares no class at all, is that valid?
    Yes - a file of only top-level functions/properties/typealiases is valid; the compiler still generates a facade class for the JVM.
  • What does the Kotlin style guide recommend for a file holding one class?
    Name the file after the class in UpperCamelCase, e.g. class OrderService in OrderService.kt.

A Kotlin file is like a labeled folder: the label is for humans, not a lock - you can put whatever papers you like inside, regardless of their individual titles.

saying these in an interview costs you the question

  • Asserting the file name must equal a class name
  • Saying a file may not contain more than one class
  • Claiming a file must contain at least one class
  • Confusing convention with a compiler requirement
  • Recommending dumping many unrelated public classes in one file as best practice

context

resolving links…