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

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)

5. Verify and finish

For every form, check visibility, imports, collisions, and compatibility. For extensions, also check nullable receivers, generics, and future-member precedence. Compile and test; on failure, narrow the API or return to step 1.

Rationalizations

Red flags

• Domain meaning on String, numbers, collections, Flow, or vendor types.
• Clock, locale, I/O, policy, or dependencies hidden in an extension.

Common mistakes

Related

• kotlin-types-value-class