Kotlin Annotations

An annotation is a small label attached to code. The label carries extra information about a class, a function, or a property. The code itself runs the same way. Tools, compilers, and frameworks read the label and act on it.

Sticky Labels on Parcels

A warehouse stamps labels on parcels: "Fragile", "This side up", "Express". The label does not change what sits inside the box. Workers and sorting machines read the label and handle the parcel properly. Annotations play the same role for code. The symbol @ starts every label.

  +---------------------+        +-------------------+
  |  @Fragile           |        |  Sorting machine  |
  |  class Vase         | -----> |  reads the label  |
  +---------------------+        |  and decides      |
                                 +-------------------+

Using Built-in Annotations

Kotlin includes several useful annotations.

@Deprecated

This label warns developers that a function is outdated and points to a better option.

@Deprecated(
    message = "Use newGreeting instead",
    replaceWith = ReplaceWith("newGreeting(name)")
)
fun oldGreeting(name: String) = "Hi $name"

fun newGreeting(name: String) = "Hello $name"

The editor draws a line through oldGreeting and offers a one-click fix.

@Suppress

This label silences a specific warning.

@Suppress("UNUSED_VARIABLE")
fun demo() {
    val spare = 10
}

Java Interoperability Labels

Several labels help Kotlin and Java cooperate:

  • @JvmStatic exposes a companion function as a true static method.
  • @JvmOverloads generates Java versions for each default argument.
  • @Throws lists exceptions for Java callers.

Annotations with Parameters

A label can carry data inside parentheses.

@Deprecated("No longer needed")
class OldTool

Creating Your Own Annotation

The keywords annotation class declare a new label.

annotation class Author(val name: String, val year: Int)

@Author("Mina", 2026)
class Report

Two rules apply. The parameters use val. The allowed types include numbers, strings, classes, enums, and arrays of those types.

Controlling Where a Label Sticks

Meta-annotations describe the behavior of a new label.

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class Audit(val reason: String)

@Audit("Handles money")
class PaymentService {
    @Audit("Charges the card")
    fun charge() { }
}
Meta-AnnotationPurpose
@TargetLists where the label may appear
@RetentionSets how long the label survives: source, binary, or runtime
@RepeatableAllows the same label twice
@MustBeDocumentedIncludes the label in generated documentation

Use-Site Targets

One Kotlin property creates several pieces: a field, a getter, and a setter. A use-site target tells Kotlin which piece receives the label.

class User(
    @get:Audit("Reads the name")
    val name: String
)

Common targets include @get:, @set:, @field:, and @param:.

Where You Meet Annotations Every Day

Android and server libraries rely on labels heavily.

 @Entity          marks a class as a database table (Room)
 @GET("users")    marks a function as a web request (Retrofit)
 @Composable      marks a function as screen content (Compose)
 @Test            marks a function as a test (JUnit)

Each label tells a tool how to treat the code. Developers write less repeated code, and the tool generates the heavy work.

Annotation Processing Flow

 You write       Tool scans         Tool acts
 labeled code    for labels         on each label
 ------------    ----------         -------------
 @Entity   ----> finds @Entity ----> builds a table
 @GET      ----> finds @GET    ----> builds a request

Good Habits

  • Use a label only when a tool or a teammate needs the extra information.
  • Write clear messages inside @Deprecated.
  • Keep custom labels small and focused.