skip to content

What is a top-level function in Kotlin, and how do you declare and call one?

level: juniorimportance: must knowfreq 70%

answer

  1. Declared outside any class, at file/package level
  2. fun keyword, no instance needed
  3. Called by simple name after import
  4. Replaces Java static utility classes
  5. private = file-scoped

basics

~10 s

A function written directly in a file, not inside any class. You declare it with the fun keyword at the top of the file and call it just by its name after importing it.

solid answer

~40 s

A top-level function is a function declared at package level with the fun keyword, outside any class, object, or interface. It lives directly in a Kotlin file and is callable from anywhere by its simple name once its package is imported (no instance or qualifier needed). Top-level functions are Kotlin's idiomatic home for utilities and factory helpers that don't belong to a type — there is no need for a Java-style static utility class. Visibility modifiers (public, internal, private) apply at file/package scope: a private top-level fun is visible only within the same file. Common examples in the standard library include listOf, println, and maxOf.

code

kotlin · 8 lines
kotlin
// File: Greetings.kt
package com.example

fun greet(name: String): String = "Hello, $name"

fun main() {
    println(greet("Ada")) // Hello, Ada — no class, no instance
}

go deeper

for a junior

Can declare a fun outside a class and call it by name with the right import.

for a middle

Explains package-level scope, visibility (private = file), and why they replace static utility classes.

for a senior

Frames them as idiomatic homes for factories/utilities and reasons about module-level visibility (internal) and API surface.

for a principal

Discusses library API design trade-offs: top-level fun vs companion factory vs extension, and namespacing/discoverability consequences.

## What is a top-level function? A **top-level function** is a function declared **directly in a Kotlin file**, outside any `class`, `object`, or `interface`. It belongs to the file's **package** rather than to a type. "Top-level" means it is at the outermost (top) lexical level of the source file. ```kotlin // File: MathUtils.kt package com.example.util fun square(x: Int): Int = x * x // top-level function ``` ## Declaring one - Use the `fun` keyword at the start of a line in the file (not indented inside a class body). - It can take parameters, return a value, and use any visibility modifier. - The optional `package` directive at the top of the file determines the package the function lives in. ## Calling one You call it by its **simple name** — no object instance and no class qualifier: ```kotlin import com.example.util.square fun main() { println(square(5)) // 25 } ``` If you are in the **same package**, you don't even need the import. From another package you either `import` it or use its fully qualified name `com.example.util.square(5)`. ## Why Kotlin has them In Java, free functions don't exist, so utilities live as `static` methods in a class (e.g. `Collections.sort`). Kotlin lets you skip that ceremony: utility and **factory** helpers that don't belong to any type become plain top-level functions. The standard library is full of them — `listOf`, `mapOf`, `println`, `maxOf`, `require`. ## Visibility Visibility modifiers apply at **file/package** scope: - `public` (default): visible everywhere. - `internal`: visible within the same Gradle/Maven module. - `private`: visible **only within the same file**. There is no `protected` for top-level declarations because there is no enclosing class to inherit from.

  • Can a top-level function be private, and what does that scope to?
    Yes. A private top-level function is visible only within the same source file — not the whole package.
  • Do you need an object instance to call a top-level function?
    No. There is no receiver; you call it directly by name, optionally importing it from its package.

Like a tool hanging on a pegboard in the workshop — grab it by name; you don't have to first build the toolbox (class) that holds it.

saying these in an interview costs you the question

  • Saying top-level functions must live inside a class or object
  • Claiming you need to instantiate something to call them
  • Confusing 'top-level' with 'companion object' methods
  • Thinking private top-level functions are package-visible rather than file-visible

context

resolving links…