Companion vs top-level functions decision in Kotlin - Visual Side-by-Side Comparison

Concept Flow - Companion vs top-level functions decision

Start

↓

Need function?

↓

Is function related to class state?

Yes→Use companion object function

No↓

Use top-level function

↓

Function called

↓

Execution

↓

End

Decide if a function belongs inside a companion object (related to class) or as a top-level function (independent). Then call and execute it.

Execution Sample

Kotlin

class MyClass {
  companion object {
    fun companionFun() = "Companion"
  }
}

fun topLevelFun() = "Top-level"

Defines a companion object function and a top-level function, showing two ways to organize functions.

Execution Table

Step	Action	Function Called	Output
1	Call MyClass.companionFun()	companionFun	"Companion"
2	Call topLevelFun()	topLevelFun	"Top-level"
3	Decide function placement	N/A	companionFun inside class, topLevelFun outside
4	End of calls	N/A	Execution complete

💡 All functions executed, decision on placement shown

Variable Tracker

Variable	Start	After Step 1	After Step 2	Final
Output	N/A	"Companion"	"Top-level"	N/A

Key Moments - 2 Insights

Why put a function inside a companion object instead of top-level?

Because companion object functions are tied to the class and can access its private members, as shown in step 1 of execution_table.

Can top-level functions access class private members?

No, top-level functions are independent and cannot access private class members, unlike companion functions (see step 3).

Visual Quiz - 3 Questions

Look at the execution_table, what is the output when calling MyClass.companionFun()?

A "Top-level"

B "Companion"

C null

D Error

💡 Hint

Check step 1 in execution_table where companionFun is called

At which step does the decision about function placement happen?

A Step 3

B Step 2

C Step 1

D Step 4

💡 Hint

Look at the 'Action' column in execution_table for decision making

If a function needs to access private class data, where should it be placed?

A Outside any class

B Top-level function

C Companion object function

D In a separate file

💡 Hint

Refer to key_moments about access to private members

Concept Snapshot

Companion object functions belong to the class and can access private members.
Top-level functions are independent and live outside classes.
Use companion functions for class-related behavior.
Use top-level functions for general utilities.
Call companion functions with ClassName.function(), top-level directly by name.

Full Transcript

This visual trace shows how to decide between companion object functions and top-level functions in Kotlin. First, if a function needs to access or relate to class state, put it inside the companion object. Otherwise, use a top-level function. The execution table shows calling both types and their outputs. Variables track outputs after each call. Key moments clarify why companion functions can access private class data, unlike top-level functions. The quiz tests understanding of outputs, decision steps, and placement rules. The snapshot summarizes the main points for quick recall.

Practice

1. Which statement best describes when to use a companion object function in Kotlin?

easy

A. When the function logically belongs to a class and should be called with the class name.

B. When the function is a general helper unrelated to any class.

C. When you want to create an instance method that requires an object.

D. When you want to define a function inside a function.

Solution

1. Step 1: Understand companion object purpose

   Companion object functions belong to a class and are called using the class name without needing an instance.

2. Step 2: Compare with other options

   Top-level functions are for general helpers, instance methods require an object, and functions inside functions are local functions.

3. Final Answer:

   When the function logically belongs to a class and should be called with the class name. -> Option A

4. Quick Check:

   Companion functions = class-related [OK]

Hint: Use companion for class-related static-like functions [OK]

Common Mistakes:

• Confusing companion functions with instance methods
• Using companion for unrelated helper functions
• Thinking companion functions need an object instance

2. Which of the following is the correct syntax to declare a companion function named create inside a Kotlin class MyClass?

easy

A. class MyClass { fun companion create() { } }

B. class MyClass { companion object { fun create() { } } }

C. class MyClass { companion fun create() { } }

D. companion object MyClass { fun create() { } }

Solution

1. Step 1: Recall companion object syntax

   In Kotlin, companion functions are declared inside a companion object block within the class.

2. Step 2: Check each option

   class MyClass { companion object { fun create() { } } } correctly declares a companion object with a function. Syntaxes like fun companion create() { } and companion fun create() { } are invalid. companion object MyClass { fun create() { } } incorrectly places companion object outside the class.

3. Final Answer:

   class MyClass { companion object { fun create() { } } } -> Option B

4. Quick Check:

   Companion object syntax = class MyClass { companion object { fun create() { } } } [OK]

Hint: Companion functions go inside companion object block [OK]

Common Mistakes:

• Writing companion fun instead of inside companion object
• Placing companion object outside the class
• Using fun companion instead of companion object

3. What will be the output of the following Kotlin code?

class Example {
    companion object {
        fun greet() = "Hello from companion"
    }
}

fun greet() = "Hello from top-level"

fun main() {
    println(Example.greet())
    println(greet())
}

medium

A. Compilation error due to function name conflict

B. "Hello from top-level" followed by "Hello from companion"

C. "Hello from companion" followed by "Hello from top-level"

D. Runtime error due to ambiguous call

Solution

1. Step 1: Identify function calls

   Example.greet() calls the companion object function returning "Hello from companion". The top-level greet() returns "Hello from top-level".

2. Step 2: Understand call order in main()

   First println prints Example.greet() output, second println prints top-level greet() output.

3. Final Answer:

   "Hello from companion" followed by "Hello from top-level" -> Option C

4. Quick Check:

   Companion vs top-level calls = "Hello from companion" followed by "Hello from top-level" [OK]

Hint: ClassName.func() calls companion; direct call is top-level [OK]

Common Mistakes:

• Assuming name conflict causes error
• Mixing up which greet() is called
• Expecting runtime ambiguity error

4. Consider this Kotlin code snippet:

class Data {
    companion object {
        fun info() = "Data info"
    }
}

fun main() {
    println(info())
}

What is the error and how to fix it?

medium

A. Error: Unresolved reference 'info'. Fix: Call as Data.info()

B. Error: Companion object missing. Fix: Add companion object

C. Error: info() must be top-level. Fix: Move info() outside class

D. No error, prints "Data info"

Solution

1. Step 1: Identify the call to info()

   The main function calls info() directly, but info() is inside Data's companion object, so it must be called with Data.info().

2. Step 2: Fix the call

   Change println(info()) to println(Data.info()) to access the companion function correctly.

3. Final Answer:

   Error: Unresolved reference 'info'. Fix: Call as Data.info() -> Option A

4. Quick Check:

   Companion functions need class name prefix [OK]

Hint: Call companion functions with ClassName.function() [OK]

Common Mistakes:

• Calling companion function without class name
• Thinking companion functions are top-level
• Trying to move companion function outside class

5. You want to create a utility function formatDate() used by multiple unrelated classes in your Kotlin project. Which approach is best and why?

hard

A. Put formatDate() inside a companion object of one class and call it via that class.

B. Define formatDate() inside a nested object inside each class.

C. Make formatDate() an instance method in each class that needs it.

D. Define formatDate() as a top-level function in a utility file for easy reuse.

Solution

1. Step 1: Analyze function usage

   The function is a utility used by many unrelated classes, so it should be accessible without class dependency.

2. Step 2: Choose best location

   Top-level functions are ideal for general helpers to avoid unnecessary class coupling. Companion objects tie functions to one class, which is not suitable here.

3. Final Answer:

   Define formatDate() as a top-level function in a utility file for easy reuse. -> Option D

4. Quick Check:

   General helpers = top-level functions [OK]

Hint: Use top-level for shared helpers, companion for class-specific [OK]

Common Mistakes:

• Placing utility in companion object of unrelated class
• Duplicating instance methods in multiple classes
• Using nested objects unnecessarily