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:
@JvmStaticexposes a companion function as a true static method.@JvmOverloadsgenerates Java versions for each default argument.@Throwslists exceptions for Java callers.
Annotations with Parameters
A label can carry data inside parentheses.
@Deprecated("No longer needed")
class OldToolCreating Your Own Annotation
The keywords annotation class declare a new label.
annotation class Author(val name: String, val year: Int)
@Author("Mina", 2026)
class ReportTwo 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-Annotation | Purpose |
|---|---|
| @Target | Lists where the label may appear |
| @Retention | Sets how long the label survives: source, binary, or runtime |
| @Repeatable | Allows the same label twice |
| @MustBeDocumented | Includes 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.
