Kotlin Academy · Lesson

Defining Annotations

Create custom ones.

Lesson 2 of 413 steps

Defining Annotations is a free Kotlin Academy lesson on CoddyKit. This is lesson 2 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Academy learning path, and your progress syncs across the web and the CoddyKit app. The Kotlin Academy course includes 4 lessons in total.

Declaring an Annotation

You define an annotation with the annotation class keywords. The simplest one carries no data and acts as a marker.

annotation class Beta

@Beta
fun newFeature() = "experimental"

fun main() {
    println(newFeature())
}

Annotation Parameters

Annotations can hold data through constructor parameters. Allowed types are limited: primitives, String, enums, other annotations, KClass, and arrays of those.

annotation class ApiVersion(val value: Int)

@ApiVersion(2)
fun endpoint() = "v2"

fun main() {
    println(endpoint())
}

@Target

@Target restricts where your annotation may be applied. You pass one or more AnnotationTarget values such as CLASS, FUNCTION, or PROPERTY.

@Target(AnnotationTarget.FUNCTION)
annotation class Loggable

@Loggable
fun process() = "processing"

fun main() {
    println(process())
}

@Retention

@Retention controls how long the annotation survives:

SOURCE — discarded by the compiler
BINARY — kept in the class file, not visible to reflection
RUNTIME — kept and visible to reflection (the default)

@Retention(AnnotationRetention.RUNTIME)
annotation class Important

@Important
class Order

fun main() {
    println("Important is readable at runtime")
}

Multiple Targets

List several targets to allow an annotation in more than one place. Here the annotation works on both classes and functions.

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class Audited

@Audited
class Account {
    @Audited
    fun withdraw() = "ok"
}

fun main() {
    println(Account().withdraw())
}

Default Parameter Values

Annotation parameters can have defaults, so callers may omit them. This keeps common cases concise.

annotation class Cache(val seconds: Int = 60)

@Cache
fun cheap() = 1

@Cache(seconds = 300)
fun expensive() = 2

fun main() {
    println("" + cheap() + " " + expensive())
}

Array Parameters

You can use array types. Provide values with the array literal syntax [ ... ] in the annotation usage.

annotation class Roles(val names: Array<String>)

@Roles(["admin", "editor"])
fun restricted() = "secret"

fun main() {
    println(restricted())
}

@Repeatable

By default an annotation can appear only once per element. Mark it @Repeatable to apply it multiple times.

@Repeatable
annotation class Tag(val value: String)

@Tag("db")
@Tag("cache")
fun layered() = "ok"

fun main() {
    println(layered())
}

Nested Annotation Parameters

An annotation parameter can itself be another annotation, letting you build structured metadata.

annotation class Author(val name: String)
annotation class Module(val owner: Author)

@Module(Author("Grace"))
class Payments

fun main() {
    println("Nested annotation metadata defined")
}

Designing Good Annotations

A well-designed annotation:

Has a clear, single purpose
Sets @Target so misuse is a compile error
Uses RUNTIME retention only when reflection needs it
Provides sensible defaults

From Definition to Use

Defining an annotation is only half the story. On its own it is inert metadata. Something must read it — usually reflection at runtime or an annotation processor at compile time. You will use reflection soon.

Quick Check

Test your understanding of defining annotations.

Answer it in the interactive lesson

Recap

You learned to define annotations:

annotation class with parameters
@Target to restrict placement
@Retention to control lifetime
@Repeatable and default values

Next: inspecting types with reflection.

Free to start

Learn Kotlin with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 51
Lessons: 203

Start learning free View the full course

Frequently Asked Questions

Is the “Defining Annotations” lesson free?

Yes — any 3 lessons of the Kotlin Academy learning path, including “Defining Annotations”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Kotlin Academy course includes 4 lessons in total.

What will I learn in “Defining Annotations”?

Create custom ones. You practise Kotlin Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Kotlin Academy?

No prior experience is required. Kotlin Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 2 of 4.

How long does the “Defining Annotations” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Kotlin Academy lesson?

Yes. Every Kotlin Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Kotlin Academy