Kotlin Academy · Lesson

Defining Annotations

Create custom ones.

Defining Annotations is a free Kotlin Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

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.

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.

Frequently asked questions

Is the “Defining Annotations” lesson free?

Yes — the full text of “Defining Annotations” is free to read here on the web, and the Kotlin Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Kotlin Academy course, upgrade to CoddyKit PRO.

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; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

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