kotlin-functions

Kotlin function ownership

Core principle

Put a function on the smallest accurate semantic owner. Extension syntax changes call shape, not ownership.

Reject primitive, common, and library-owned extensions by default: they create false ownership, domain pollution, noisy completion/imports, and collisions.

Procedure

Apply in order.

1. Name the semantic owner

Name the operation and the concept that owns it. If ownership is unclear, stop before selecting syntax.

2. Reject a misleading receiver early

For String, primitives, collections, Flow, framework, or third-party receivers, require all:

• Narrow private/internal cohesive scope.
• Valid for every receiver value.
• No policy, state, I/O, or dependency.
• Materially clearer receiver syntax.
• No better project-owned owner.

Any failure forbids an extension on that receiver; choose a non-extension form in step 3. private fun <T> MutableList<T>.swap(...) can pass: it is list-native, policy-free, and algorithm-local.

3. Choose the function form

Meaning	Prefer
Project-owned intrinsic behavior	Member
Cross-type, stateless operation	Top-level function
Construction or parsing	Target factory or named top-level function
Retained policy, state, I/O, clock, locale, or dependencies	Injected service/collaborator
Type-native operation with a clearer receiver and every step-2 gate passed	Extension

Use a service/collaborator only when behavior retains policy, state, I/O, clock/locale, or dependencies; otherwise use explicit parameters on a stateless function.

4. Move behavior and callers

Move the implementation, then update calls, imports, and function references. Preserve or deprecate public entry points unless this is an explicit breaking release; add non-public migration support only for concrete consumers.

// Before: String falsely owns UserId construction.
fun String.toUserId(): UserId = UserId(this)

// After: UserId owns construction.
@JvmInline
value class UserId private constructor(val value: String) {
    companion object {
        fun parse(raw: String): UserId = UserId(raw)
    }
}

val id = UserId.parse(raw)