Java ships with a small set of annotations in the core language and platform that every developer uses regularly - some daily, some occasionally, and some almost never but always at exactly the right moment when they are needed. These are not framework annotations like @Autowired or @Entity: they are part of the language itself, defined in java.lang and java.lang.annotation, and understood directly by the compiler and the JVM. Each one exists because it solves a specific class of problem that comments and naming conventions cannot solve - it creates a contract the compiler actually checks.

What Are Built-in Annotations?

Java's built-in annotations fall into two groups: compiler annotations that give direct instructions to javac, and meta-annotations that describe how other annotations behave. This article covers the compiler annotations in depth and introduces the meta-annotations briefly, since they are covered fully in the custom annotations topic.

COMPILER ANNOTATIONS (in java.lang):
  @Override           - verify this method actually overrides a supertype method
  @Deprecated         - warn every caller that this API is scheduled for removal
  @SuppressWarnings   - silence a named category of compiler warning at one site
  @FunctionalInterface - verify this interface has exactly one abstract method
  @SafeVarargs        - suppress heap pollution warnings for varargs generics

META-ANNOTATIONS (in java.lang.annotation):
  @Retention          - controls how long an annotation survives
  @Target             - restricts where an annotation can be placed
  @Documented         - includes an annotation in Javadoc output
  @Inherited          - propagates a class annotation to subclasses
  @Repeatable         - allows the same annotation on one element more than once

Basic Overview - What Each Annotation Does and Why

@Override
  Fresher view  : write this above a method that is supposed to
                  override a parent class method. If you misspell the
                  name or get the parameters wrong, the compiler
                  catches the error immediately instead of silently
                  creating a second, unrelated method
  Deeper view   : the compiler checks that the annotated method's
                  signature matches at least one accessible method in
                  a superclass or implemented interface. If nothing
                  matches, COMPILE ERROR. This annotation is erased
                  at compile time (RetentionPolicy.SOURCE) - it is
                  purely a compile-time safety net with zero runtime cost

@Deprecated
  Fresher view  : put this on a method or class you want to retire -
                  every team member who calls it sees a compiler warning
                  telling them to stop using it
  Deeper view   : survives into the .class file (RetentionPolicy.RUNTIME)
                  so IDEs and reflection can see it too. The 'since'
                  and 'forRemoval' elements (added Java 9) provide
                  machine-readable context about the deprecation.
                  @Deprecated on an annotation type deprecates the
                  annotation itself, not just the types it annotates

@SuppressWarnings
  Fresher view  : silence one specific compiler warning at one specific
                  call site - not globally, just here
  Deeper view   : RetentionPolicy.SOURCE - discarded after compile.
                  Takes a String[] of warning category names. The
                  categories are compiler-specific ("unchecked",
                  "deprecation", "rawtypes", "serial", "unused", etc.)
                  The JLS does not standardize them - each compiler
                  defines what it accepts. "all" suppresses everything
                  but is widely considered a code smell

@FunctionalInterface
  Fresher view  : declare that an interface is meant to be a lambda
                  target. If someone adds a second abstract method,
                  the compiler immediately errors
  Deeper view   : this is a documentation and verification annotation -
                  an interface with one abstract method IS functionally
                  usable as a lambda target whether or not it has
                  @FunctionalInterface. The annotation's job is to
                  PROTECT that property: make adding a second abstract
                  method a compile error instead of silently breaking
                  every lambda that targets this interface

@SafeVarargs
  Fresher view  : used on methods that take generic varargs parameters
                  to tell the compiler "I checked, this is safe, stop
                  warning me about heap pollution"
  Deeper view   : generic arrays cannot be created safely in Java due
                  to type erasure - T[] is just Object[] at runtime.
                  When a method takes T... (varargs becomes T[]), the
                  compiler warns because it cannot guarantee the
                  caller's generic type information is preserved.
                  @SafeVarargs is a PROMISE by the author that the
                  vararg array is only read, never written or leaked,
                  making the operation safe despite the compiler's
                  uncertainty. Requires final, static, or private on
                  the method (Java 9+ also allows constructors)

@Override - The Most Important Safety Annotation

@Override costs nothing at runtime and prevents one of the most persistent bugs in object-oriented code: a method that was supposed to override a parent's method but silently became its own unrelated method because of a typo, a parameter mismatch, or a signature change in the parent.

Java

Try it out

// File: OverrideDemo.java

public class OverrideDemo {

    interface PaymentProcessor {
        boolean process(String orderId, double amount);
        default String processorName() { return "Generic Processor"; }
    }

    // Correct use of @Override
    static class UpiProcessor implements PaymentProcessor {

        // Compiler verifies this matches PaymentProcessor.process(String, double)
        // exactly. Wrong parameter type, wrong name, or wrong return type
        // would be a COMPILE ERROR, not a silent new method
        @Override
        public boolean process(String orderId, double amount) {
            System.out.println("Processing UPI payment: " + orderId + " Rs." + amount);
            return amount <= 100000.0;
        }

        // @Override works on default method overrides too
        @Override
        public String processorName() {
            return "UPI Processor";
        }
    }

    // What happens WITHOUT @Override when there's a mistake
    static class BrokenProcessor implements PaymentProcessor {

        // Typo: 'orderid' instead of 'orderId'. Without @Override,
        // this compiles as a NEW method named 'processOrder'.
        // PaymentProcessor.process() is never overridden - the default
        // null behavior of the interface applies instead.
        // With @Override, this would be a COMPILE ERROR immediately.
        public boolean processOrder(String orderid, double amount) {
            return true; // this method is NEVER called via PaymentProcessor reference
        }

        // This is the method the interface contract ACTUALLY needs
        // but it was never written because the developer didn't
        // notice 'processOrder' is not 'process'
        @Override
        public boolean process(String orderId, double amount) {
            return false; // placeholder - real implementation missing
        }
    }

    public static void main(String[] args) {
        UpiProcessor upi = new UpiProcessor();
        System.out.println(upi.processorName() + ": " + upi.process("ORD-101", 499.0));
        System.out.println(upi.processorName() + ": " + upi.process("ORD-102", 150001.0));
    }
}

Output:
Processing UPI payment: ORD-101 Rs.499.0
UPI Processor: true
Processing UPI payment: ORD-102 Rs.150001.0
UPI Processor: false

@Override applies in four situations: overriding a concrete method from a superclass, overriding an abstract method from an abstract class, providing a concrete implementation of an interface method, and overriding a default method from an interface. All four are valid targets. The annotation itself has RetentionPolicy.SOURCE - it is used by the compiler and discarded, leaving no trace in the compiled class file.

@Deprecated - Retiring Code Safely

@Deprecated is the formal way to signal that an API element is no longer the right choice, without removing it immediately and breaking every caller. It does not prevent the deprecated item from being called - it makes the call site show a compiler warning, which IDEs render as a strikethrough over the deprecated name, so developers cannot miss it.

Java

Try it out

// File: DeprecatedDemo.java

public class DeprecatedDemo {

    static class NotificationService {

        // The old method - deprecated since version 2.0, scheduled for
        // removal. 'since' and 'forRemoval' are machine-readable and
        // visible in IDE tooltips and Javadoc
        @Deprecated(since = "2.0", forRemoval = true)
        public void sendSms(String mobile, String message) {
            System.out.println("[DEPRECATED] SMS to " + mobile + ": " + message);
        }

        // The new method callers should use instead
        public void sendNotification(String userId, String channel, String message) {
            System.out.println("Notification -> " + channel + " for " + userId + ": " + message);
        }

        // A method that internally uses the deprecated API - suppressing
        // the warning here because this is the MIGRATION BRIDGE that
        // knows what it is doing, not an accidental use of the old API
        @SuppressWarnings("deprecation")
        public void migrateLegacySmsCall(String mobile, String message) {
            sendSms(mobile, message); // deliberate use - bridge method
        }
    }

    public static void main(String[] args) {
        NotificationService service = new NotificationService();

        System.out.println("=== New API ===");
        service.sendNotification("USER-42", "PUSH", "Your order has been dispatched");

        System.out.println();

        System.out.println("=== Deprecated API (produces compiler warning at this call site) ===");
        service.sendSms("9876543210", "Your order is on the way");

        System.out.println();

        System.out.println("=== Bridge method suppressing its own deprecation warning ===");
        service.migrateLegacySmsCall("9999900000", "Legacy call routed");
    }
}

Output:
=== New API ===
Notification -> PUSH for USER-42: Your order has been dispatched

=== Deprecated API (produces compiler warning at this call site) ===
[DEPRECATED] SMS to 9876543210: Your order is on the way

=== Bridge method suppressing its own deprecation warning ===
[DEPRECATED] SMS to 9999900000: Legacy call routed

One subtlety worth knowing: a class or method can be annotated with BOTH @Deprecated in the code and @deprecated in the Javadoc comment. They serve different audiences. The annotation is machine-readable: the compiler, the IDE, and reflection all see it. The Javadoc tag is human-readable: it is where you explain WHY the element is deprecated and what to use instead. Using only the annotation without a Javadoc explanation leaves callers without guidance; using only the Javadoc tag without the annotation means the IDE cannot show a strikethrough or warning automatically.

@SuppressWarnings - Targeted Compiler Silence

@SuppressWarnings silences a specific category of compiler warning at exactly one location. It takes a String[] of warning category names - most commonly a single string. The effect is local: the warning is suppressed for the annotated element and everything nested inside it, and nowhere else.

Java

Try it out

// File: SuppressWarningsDemo.java

import java.util.ArrayList;
import java.util.List;

public class SuppressWarningsDemo {

    // An older utility method written before generics - uses raw types.
    // The compiler warns about "rawtypes" and "unchecked" operations.
    // @SuppressWarnings is appropriate here because this is a LEGACY
    // INTEROP method where raw types are unavoidable. The method name
    // and comment communicate the context; the suppression is justified.
    @SuppressWarnings({"rawtypes", "unchecked"})
    static List wrapLegacyData(Object[] rawData) {
        List result = new ArrayList(); // raw type - required for legacy API compatibility
        for (Object item : rawData) {
            result.add(item);
        }
        return result;
    }

    // @SuppressWarnings applies to the method body AND any nested
    // elements - here it covers only the one cast that we know is
    // safe but the compiler cannot verify due to type erasure
    @SuppressWarnings("unchecked")
    static <T> T firstOrDefault(List<?> items, T defaultValue) {
        if (items == null || items.isEmpty()) return defaultValue;
        return (T) items.get(0); // cast is safe: caller controls T and the list
    }

    public static void main(String[] args) {
        Object[] legacyArray = {"Notebook", "Pen", "Eraser"};
        List legacyList = wrapLegacyData(legacyArray);
        System.out.println("Legacy list: " + legacyList);

        List<String> products = List.of("Laptop", "Tablet");
        String first = firstOrDefault(products, "None");
        System.out.println("First product: " + first);

        String fallback = firstOrDefault(null, "Default Product");
        System.out.println("Fallback: " + fallback);
    }
}

Output:
Legacy list: [Notebook, Pen, Eraser]
First product: Laptop
Fallback: Default Product

The warning categories most commonly used with @SuppressWarnings are "unchecked" (for unchecked generic casts), "deprecation" (for calling deprecated APIs intentionally), "rawtypes" (for using raw generic types in legacy interop code), "serial" (for classes implementing Serializable without declaring serialVersionUID), and "unused" (for variables or parameters that exist but are currently unused, often intentionally in library code). Applying "all" to silence every possible warning everywhere is a common mistake in fresher code - it hides genuine problems alongside the intended suppression and makes the code less trustworthy to reviewers.

@FunctionalInterface - Protecting Lambda Targets

@FunctionalInterface declares that an interface is designed to be used as a lambda expression target - exactly one abstract method, no more. Any interface with one abstract method is technically a functional interface whether it has this annotation or not. What the annotation adds is a compiler-enforced guarantee: if anyone adds a second abstract method to the interface, the code does not compile at all, and every lambda that targets it is not silently broken.

Java

Try it out

// File: FunctionalInterfaceDemo.java

import java.util.List;
import java.util.function.Predicate;

public class FunctionalInterfaceDemo {

    // @FunctionalInterface declares the design intent AND protects it.
    // Adding a second abstract method here would immediately break
    // the compilation of this file, rather than silently breaking
    // every lambda that implements OrderFilter elsewhere
    @FunctionalInterface
    interface OrderFilter {
        boolean accept(String orderId, double amount, String status);

        // Default methods are NOT abstract - having them does not
        // violate @FunctionalInterface. They provide shared behavior
        // without counting as the "one abstract method"
        default OrderFilter and(OrderFilter other) {
            return (orderId, amount, status) ->
                this.accept(orderId, amount, status) && other.accept(orderId, amount, status);
        }

        // Static methods are also fine - same reason
        static OrderFilter acceptAll() {
            return (orderId, amount, status) -> true;
        }
    }

    @FunctionalInterface
    interface AmountFormatter {
        String format(double amount);
        // String anotherMethod(double amount); <- adding this would be a COMPILE ERROR
        // because @FunctionalInterface enforces exactly one abstract method
    }

    public static void main(String[] args) {
        // Lambda implementing the three-parameter functional interface
        OrderFilter highValueFilter = (orderId, amount, status) -> amount >= 5000.0;
        OrderFilter confirmedFilter = (orderId, amount, status) -> "CONFIRMED".equals(status);

        // Composing two OrderFilters using the default 'and' method
        OrderFilter highValueConfirmed = highValueFilter.and(confirmedFilter);

        List<Object[]> orders = List.of(
            new Object[]{"ORD-1", 7500.0, "CONFIRMED"},
            new Object[]{"ORD-2", 2000.0, "CONFIRMED"},
            new Object[]{"ORD-3", 6000.0, "PENDING"},
            new Object[]{"ORD-4", 8000.0, "CONFIRMED"}
        );

        System.out.println("=== Orders passing highValueConfirmed filter ===");
        for (Object[] order : orders) {
            String orderId = (String) order[0];
            double amount  = (double) order[1];
            String status  = (String) order[2];

            if (highValueConfirmed.accept(orderId, amount, status)) {
                System.out.println("  Accepted: " + orderId + " Rs." + amount + " [" + status + "]");
            }
        }

        System.out.println();

        // Lambda implementing the single-parameter formatter
        AmountFormatter inrFormatter = amount -> "Rs. " + String.format("%.2f", amount);
        System.out.println("Formatted: " + inrFormatter.format(1249.5));

        // java.util.function.Predicate is itself @FunctionalInterface
        Predicate<String> startsWithORD = id -> id.startsWith("ORD-");
        System.out.println("ORD-1 starts with ORD-? " + startsWithORD.test("ORD-1"));
    }
}

Output:
=== Orders passing highValueConfirmed filter ===
  Accepted: ORD-1 Rs.7500.0 [CONFIRMED]
  Accepted: ORD-4 Rs.8000.0 [CONFIRMED]

Formatted: Rs. 1249.50
ORD-1 starts with ORD-? true

The standard library's entire java.util.function package - Predicate<T>, Function<T,R>, Supplier<T>, Consumer<T>, BiFunction<T,U,R>, and the rest - are all @FunctionalInterface. Understanding that annotation explains why those interfaces can be implemented as lambdas: the guarantee that exactly one abstract method exists makes the lambda-to-interface binding unambiguous.

@SafeVarargs - Generic Varargs Heap Pollution

This is the most specialized of the built-in compiler annotations - rarely written but important to recognize when encountered. It suppresses a specific class of warning that appears when a method takes a generic varargs parameter.

The underlying issue is a gap between Java's type erasure and its array variance rules: generic arrays cannot actually be created safely, so T... parameters (which the compiler converts to T[]) generate a "heap pollution" warning because the runtime array is Object[] and the compiler cannot enforce that only T objects are placed in it. When the method body only reads from the vararg array and never stores foreign values into it or leaks the array reference, the operation is actually safe - and @SafeVarargs is how the author declares that they have verified this.

Java

Try it out

// File: SafeVarargsDemo.java

import java.util.ArrayList;
import java.util.List;

public class SafeVarargsDemo {

    // WITHOUT @SafeVarargs, this method generates:
    // "Possible heap pollution from parameterized vararg type List<T>"
    // The annotation suppresses that warning because this method
    // ONLY READS from 'listsToCombine' and does not store anything
    // into the array itself - making it genuinely safe despite the
    // compiler's inability to verify it statically
    @SafeVarargs
    static <T> List<T> combineAll(List<T>... listsToCombine) {
        List<T> combined = new ArrayList<>();
        for (List<T> list : listsToCombine) {
            combined.addAll(list); // reading only - never writing to listsToCombine[N]
        }
        return combined;
    }

    // @SafeVarargs also PREVENTS call-site warnings when the method
    // is called with generic list arguments. Without it, every call
    // site like the ones below would also show a warning.

    public static void main(String[] args) {
        List<String> premiumProducts = List.of("Laptop", "Tablet");
        List<String> standardProducts = List.of("Notebook", "Pen");
        List<String> budgetProducts = List.of("Eraser", "Ruler");

        List<String> allProducts = combineAll(premiumProducts, standardProducts, budgetProducts);
        System.out.println("All products: " + allProducts);
        System.out.println("Total count : " + allProducts.size());
    }
}

Output:
All products: [Laptop, Tablet, Notebook, Pen, Eraser, Ruler]
Total count : 6

@SafeVarargs can only be applied to methods that cannot be overridden - static methods, final instance methods, private instance methods, and constructors. This restriction exists because the safety guarantee depends on knowing exactly which method body will execute, and an overriding method could violate the contract its parent declared safe. The java.util.Arrays.asList() and Collections.addAll() in the standard library both carry @SafeVarargs for exactly this reason.

Real-World Example - Swiggy Order Processing Pipeline

A food-delivery platform's order processing code evolves over time: old routing methods get replaced, new functional-interface-based pipeline stages are introduced, and the transition period requires both the old and new APIs to coexist cleanly - deprecated warnings guiding developers toward the new approach, @Override ensuring every stage correctly implements the pipeline contract, and @FunctionalInterface protecting the lambda-friendly stage interfaces.

Java

Try it out

// File: PipelineStage.java

@FunctionalInterface
public interface PipelineStage<T> {

    T process(T input);

    // Compose two stages - 'this' stage runs first, then 'next'
    default PipelineStage<T> andThen(PipelineStage<T> next) {
        return input -> next.process(this.process(input));
    }
}

Java

Try it out

// File: OrderEvent.java

public class OrderEvent {

    private String orderId;
    private String restaurantId;
    private String status;
    private double totalAmount;
    private boolean fraudFlagged;

    public OrderEvent(String orderId, String restaurantId, double totalAmount) {
        this.orderId = orderId;
        this.restaurantId = restaurantId;
        this.totalAmount = totalAmount;
        this.status = "RECEIVED";
        this.fraudFlagged = false;
    }

    public String getOrderId()       { return orderId; }
    public String getRestaurantId()  { return restaurantId; }
    public String getStatus()        { return status; }
    public double getTotalAmount()   { return totalAmount; }
    public boolean isFraudFlagged()  { return fraudFlagged; }

    public void setStatus(String status)           { this.status = status; }
    public void setFraudFlagged(boolean flagged)   { this.fraudFlagged = flagged; }

    @Override
    public String toString() {
        return "OrderEvent[" + orderId + ", " + restaurantId
            + ", Rs." + totalAmount + ", status=" + status
            + ", fraud=" + fraudFlagged + "]";
    }
}

Java

Try it out

// File: FraudCheckStage.java

public class FraudCheckStage implements PipelineStage<OrderEvent> {

    private static final double HIGH_VALUE_THRESHOLD = 3000.0;

    // @Override verifies this correctly implements PipelineStage.process(OrderEvent)
    // A signature mismatch here would be a compile error, not a silent
    // "FraudCheckStage never actually ran in the pipeline" bug
    @Override
    public OrderEvent process(OrderEvent event) {
        if (event.getTotalAmount() > HIGH_VALUE_THRESHOLD) {
            event.setFraudFlagged(true);
            System.out.println("  [FRAUD_CHECK] Flagged high-value order: " + event.getOrderId());
        } else {
            System.out.println("  [FRAUD_CHECK] Passed: " + event.getOrderId());
        }
        return event;
    }
}

Java

Try it out

// File: RestaurantRouter.java

public class RestaurantRouter implements PipelineStage<OrderEvent> {

    // Deprecated routing method - the old API assigned restaurants by
    // a static lookup table. The new approach (routeToNearestKitchen)
    // uses live location data.
    @Deprecated(since = "3.0", forRemoval = true)
    public String assignByStaticTable(String restaurantId) {
        return "KITCHEN-" + restaurantId.hashCode() % 10;
    }

    @Override
    public OrderEvent process(OrderEvent event) {
        String kitchen = routeToNearestKitchen(event.getRestaurantId());
        event.setStatus("ROUTED_TO_" + kitchen);
        System.out.println("  [ROUTER] " + event.getOrderId() + " -> " + kitchen);
        return event;
    }

    private String routeToNearestKitchen(String restaurantId) {
        return "KITCHEN-CENTRAL-" + restaurantId.substring(0, 3).toUpperCase();
    }
}

Java

Try it out

// File: OrderPipelineDemo.java

public class OrderPipelineDemo {

    public static void main(String[] args) {
        FraudCheckStage fraudCheck = new FraudCheckStage();
        RestaurantRouter router = new RestaurantRouter();

        // Lambda stage - PipelineStage is @FunctionalInterface, so this compiles
        PipelineStage<OrderEvent> statusFinalizer = event -> {
            if (!event.isFraudFlagged()) {
                event.setStatus("CONFIRMED");
            } else {
                event.setStatus("HELD_FOR_REVIEW");
            }
            System.out.println("  [FINALIZER] " + event.getOrderId() + " -> " + event.getStatus());
            return event;
        };

        // Compose the full pipeline using andThen()
        PipelineStage<OrderEvent> fullPipeline = fraudCheck
            .andThen(router)
            .andThen(statusFinalizer);

        System.out.println("=== Processing a normal order ===");
        OrderEvent normalOrder = new OrderEvent("ORD-5001", "RST-north", 850.0);
        OrderEvent normalResult = fullPipeline.process(normalOrder);
        System.out.println("Final: " + normalResult);

        System.out.println();

        System.out.println("=== Processing a high-value order ===");
        OrderEvent highValueOrder = new OrderEvent("ORD-5002", "RST-south", 4500.0);
        OrderEvent highValueResult = fullPipeline.process(highValueOrder);
        System.out.println("Final: " + highValueResult);
    }
}

Output:
=== Processing a normal order ===
  [FRAUD_CHECK] Passed: ORD-5001
  [ROUTER] ORD-5001 -> KITCHEN-CENTRAL-RST
  [FINALIZER] ORD-5001 -> CONFIRMED
Final: OrderEvent[ORD-5001, RST-north, Rs.850.0, status=CONFIRMED, fraud=false]

=== Processing a high-value order ===
  [FRAUD_CHECK] Flagged high-value order: ORD-5002
  [ROUTER] ORD-5002 -> KITCHEN-CENTRAL-RST
  [FINALIZER] ORD-5002 -> HELD_FOR_REVIEW
Final: OrderEvent[ORD-5002, RST-south, Rs.4500.0, status=HELD_FOR_REVIEW, fraud=true]

@FunctionalInterface on PipelineStage means the andThen composition and the inline lambda for statusFinalizer are unambiguous. @Override on FraudCheckStage.process() and RestaurantRouter.process() means if PipelineStage's method signature ever changes, both implementations fail at compile time rather than silently becoming dead code that the pipeline never calls. @Deprecated(since="3.0", forRemoval=true) on assignByStaticTable makes the migration path visible to every developer who opens RestaurantRouter.

Built-in Annotations - Quick Reference

Annotation	Package	Retention	Target	What It Does
`@Override`	`java.lang`	SOURCE	METHOD	Compile error if the method does not override a supertype method
`@Deprecated`	`java.lang`	RUNTIME	Most elements	Compile warning at every call site; since/forRemoval in Java 9+
`@SuppressWarnings`	`java.lang`	SOURCE	Most elements	Silences named warning categories at this element and its contents
`@FunctionalInterface`	`java.lang`	RUNTIME	ANNOTATION_TYPE, TYPE (interface only)	Compile error if the interface has more or fewer than one abstract method
`@SafeVarargs`	`java.lang`	RUNTIME	METHOD, CONSTRUCTOR	Suppresses heap pollution warnings for generic varargs; method must be non-overridable

Best Practices

Write @Override on every method that overrides or implements - without exception. The annotation costs zero characters of runtime overhead and prevents an entire class of silent bug. A codebase where @Override appears inconsistently is one where typos in method names go undetected; a codebase where it appears consistently lets the compiler catch them all at compile time. IDEs will flag missing @Override annotations, and most team style guides enforce this.

Always pair @Deprecated in code with @deprecated in Javadoc, explaining why and what to use instead. The annotation triggers the warning; the Javadoc gives the reader context. @Deprecated(since = "X.Y", forRemoval = true) is more informative than @Deprecated alone - the since tells when the decision was made, and forRemoval = true makes clear this is not just a soft suggestion.

Scope @SuppressWarnings as narrowly as possible. Apply it to a single statement (via a local variable or a very short method) rather than an entire class. The goal is to suppress one specific, understood warning at one specific, justified location - not to turn warnings off broadly. Every @SuppressWarnings is a decision that a warning was understood and accepted; a broad scope hides future warnings that might be genuine problems.

Use @FunctionalInterface on every interface you design as a lambda target. It is not required for the interface to work with lambdas, but without it there is nothing stopping a future maintainer from adding a second abstract method and silently breaking dozens of lambda usages across the codebase. The annotation makes that breakage a compile error instead.

Reserve @SafeVarargs only for methods that genuinely do not write to the vararg array or leak it. The annotation is a promise - "I checked this". If the method stores values of unknown type into the array, or passes the array to some other code that might, the promise is broken and real heap corruption can occur at runtime as a ClassCastException from code that appears unrelated.

Common Mistakes

Mistake 1 - Omitting @Override and Missing a Signature Change

Java

Try it out

// The scenario that makes @Override indispensable:
// PaymentProcessor is in a library and its method signature changes

interface PaymentProcessor {
    // Library version 2.0 changes the parameter from 'String orderId'
    // to 'long orderId' - a breaking change
    boolean process(long orderId, double amount); // CHANGED
}

// WITHOUT @Override - this compiles silently in both library versions
// but is now a DEAD METHOD that the interface never calls
class UpiProcessor implements PaymentProcessor {
    public boolean process(String orderId, double amount) { // old signature
        return true;
        // After the library upgrade, UpiProcessor.process(String, double)
        // still compiles but is no longer the implementation of the
        // interface method - it is an unrelated second method
        // The interface method has NO implementation -> runtime failure
    }

    // This line below would catch the error:
    // @Override  <- WOULD BE A COMPILE ERROR with the new signature
}

// WITH @Override - the signature change is caught immediately
class UpiProcessorSafe implements PaymentProcessor {
    @Override
    public boolean process(long orderId, double amount) {
        // The compiler forces this to match the current interface signature
        return orderId > 0;
    }
}

Mistake 2 - Using @SuppressWarnings("all") as a Blanket Silencer

Java

Try it out

import java.util.ArrayList;
import java.util.List;

// WRONG - "all" silences every warning on this method, including
// future warnings about genuinely problematic code. This is a
// code review red flag - it signals "I didn't want to understand
// this warning, so I suppressed everything"
@SuppressWarnings("all")
static void processOrdersBad(List orders) {
    for (Object order : orders) {
        String id = (String) order;
        System.out.println(id);
    }
}

// CORRECT - suppress ONLY the specific category that is understood
// and intentional. Any OTHER warning in this method will still be
// reported, which is exactly what's wanted
@SuppressWarnings("unchecked")
static void processOrdersGood(List<?> orders) {
    for (Object order : orders) {
        // This cast generates "unchecked" - suppressed only for this
        // understood-and-accepted risk. "rawtypes", "deprecation", or
        // any other category would still be reported normally
        String id = (String) order;
        System.out.println(id);
    }
}

Mistake 3 - Expecting @FunctionalInterface to Work on Abstract Classes

Java

Try it out

// WRONG - @FunctionalInterface applies to INTERFACES only.
// An abstract class with one abstract method is NOT the same thing -
// it cannot be implemented with a lambda expression, and placing
// @FunctionalInterface on it is a COMPILE ERROR
@FunctionalInterface  // COMPILE ERROR: FunctionalInterface annotation requires a single abstract method
abstract class AbstractProcessor {
    abstract void process(String input);
}

// CORRECT - @FunctionalInterface applies only to an interface
// declaration. An abstract class with one method can be used with
// an anonymous class, but NOT with a lambda.
@FunctionalInterface
interface Processor {
    void process(String input);
}

// Lambda works with the interface
Processor processor = input -> System.out.println("Processing: " + input);

// Abstract class still requires either a named subclass or anonymous class
AbstractProcessor abstractProcessor = new AbstractProcessor() {
    @Override
    void process(String input) { System.out.println("Processing: " + input); }
};

Mistake 4 - Applying @SafeVarargs to an Overridable Instance Method

Java

Try it out

import java.util.List;

// WRONG - @SafeVarargs on a non-final, non-static, non-private
// instance method. COMPILE ERROR: @SafeVarargs is not allowed on
// non-final instance methods - because the safety guarantee could
// be violated by a subclass that overrides this method and writes
// to the vararg array
class UnsafeVarargsUsage {
    @SafeVarargs  // COMPILE ERROR
    public <T> List<T> combine(List<T>... lists) {
        return new java.util.ArrayList<>();
    }
}

// CORRECT - must be final, static, or private on instance methods,
// or used on a constructor
class SafeVarargsUsage {
    @SafeVarargs
    public final <T> List<T> combine(List<T>... lists) { // 'final' added
        List<T> result = new java.util.ArrayList<>();
        for (List<T> list : lists) result.addAll(list);
        return result;
    }
}

Interview Questions

Q1. What is @Override and why should it always be used when overriding a method?

@Override is a compiler annotation that instructs javac to verify that the annotated method genuinely overrides or implements a method from a superclass or interface. If the method's signature does not match any accessible method in the supertype - because of a typo, a wrong parameter type, or a signature change in a library - the compiler reports an error immediately at the annotation. Without @Override, a mismatched signature simply creates a new, unrelated method that the supertype never calls, which is a silent runtime bug rather than a compile-time failure. The annotation has RetentionPolicy.SOURCE and zero runtime overhead.

Q2. What is the difference between @Deprecated in code and @deprecated in Javadoc?

@Deprecated (capital D) is the annotation: it is machine-readable, causes compilers and IDEs to emit warnings at every call site, and since Java 9 carries since and forRemoval elements that tools can read programmatically. It survives into the compiled class file (RetentionPolicy.RUNTIME). @deprecated (lowercase d) is the Javadoc tag: it is human-readable, visible only in generated documentation, and is where the explanation goes - why the element is deprecated and what the caller should use instead. Both should always be used together when deprecating an API: the annotation creates the warning, the Javadoc explains the migration path.

Q3. What warning categories does @SuppressWarnings accept, and is "all" a good choice?

The warning categories are compiler-specific strings, not standardized by the Java Language Specification. The most commonly used ones across standard javac are "unchecked" (unchecked generic casts), "deprecation" (calling deprecated APIs), "rawtypes" (using raw generic types), "serial" (missing serialVersionUID), and "unused". Using "all" suppresses every warning the compiler would otherwise report, which is generally considered a poor practice in production code: it hides genuine problems alongside the intended suppression, signals that the developer did not bother understanding the warning, and makes future problematic code in the same scope invisible. The correct approach is to use the most specific category that covers exactly the warning being suppressed.

Q4. What exactly does @FunctionalInterface enforce, and what does it not enforce?

@FunctionalInterface enforces that the annotated interface has exactly one abstract method at compile time. If the interface has zero abstract methods or more than one, the annotation causes a compile error. What it does NOT enforce: it does not restrict the number of default methods (which provide implementations and do not count as abstract), static methods, or constants. An interface without @FunctionalInterface that has exactly one abstract method is still a valid lambda target - the annotation's job is to protect that property as the interface evolves, not to enable it.

Q5. What is heap pollution in the context of generic varargs, and what role does @SafeVarargs play?

Heap pollution occurs when a variable of a parameterized type refers to an object that is not actually of that type - specifically, when type erasure causes a generic array (like T[] from T... varargs) to accept elements of the wrong type at runtime, which then cause unexpected ClassCastException from unrelated code that reads the array assuming the type is correct. @SafeVarargs is a promise by the method's author that the vararg array is only read from (via for-each or indexed access), never written to with potentially wrong-typed values, and never leaked to code that might write to it - making the operation safe despite the compiler's inability to verify this statically. It suppresses both the warning on the method declaration and the warning at every call site that passes generic collections as vararg arguments.

Q6. In what order do the built-in annotations interact with each other in real code?

They complement rather than conflict with each other. @Override is used alongside any instance method that overrides a supertype, including methods in classes that also carry @Deprecated. @Deprecated is placed on the element being retired, and callers of that element use @SuppressWarnings("deprecation") when the call is intentional (typically in migration bridge code). @FunctionalInterface is placed on the interface declaration and interacts with @Override at the implementation side: classes that implement the functional interface's single abstract method should use @Override on it. @SafeVarargs is independent of the others and appears only on non-overridable methods with generic vararg parameters. None of these annotations conflict - a single method or class can carry multiple of them simultaneously if each one is appropriate for that element's purpose.

FAQs

Can @Override be used on interface default methods?

Yes. Overriding a default method in a class that implements the interface is a valid override, and @Override applies to it the same way it applies to any other override. If the implementing class declares a method with the same name and parameters as the interface's default method, it is an override and should carry @Override. Similarly, if an interface extends another interface and overrides one of its default methods with a new default implementation, @Override is valid on that too.

Does @Deprecated prevent the deprecated code from compiling or running?

No. @Deprecated generates a compile-time warning at the call site, not an error. The deprecated code compiles normally, runs normally, and produces the same results it always has. The only effect is the warning, which IDE tools typically display as a strikethrough over the deprecated name. Code removal happens when the API is actually deleted in a later version - forRemoval = true signals that deletion is planned, but does not cause it.

Can @SuppressWarnings suppress errors, not just warnings?

No. Compiler errors are unconditional - they always prevent compilation and cannot be suppressed by any annotation. @SuppressWarnings applies only to warnings, which are optional diagnostic messages the compiler emits alongside a successful compilation. If the compiler would have produced an error, @SuppressWarnings has no effect on it.

Is a class with @FunctionalInterface and one abstract method usable with method references?

Yes. Method references are another form of the same lambda-to-functional-interface binding. Any functional interface - whether it has @FunctionalInterface or not - can be the target of both lambda expressions and method references. @FunctionalInterface does not change this capability; it only adds the compile-time enforcement that the interface remains a valid functional interface as it evolves.

Why does @SafeVarargs require the method to be non-overridable?

The annotation is a guarantee about the specific method body's behavior: "this code only reads the vararg array." If the method could be overridden, a subclass could provide a different body that writes to the array or leaks it to unsafe code - violating the guarantee. Since @SafeVarargs suppresses the warning at both the declaration and all call sites, a violated guarantee would produce silent heap pollution with no warning anywhere. Restricting it to static, final, private, or constructors ensures the promise can only be made for a method body that is known definitively at compile time.

Can you put multiple annotations on the same element?

Yes. Multiple annotations can be stacked on a single element in any order. @Override and @SuppressWarnings("unchecked") can appear on the same method simultaneously if the override also involves an unchecked cast. A class can carry both @Deprecated and @SuppressWarnings("deprecation") if it is deprecated but also internally calls other deprecated APIs. The compiler processes each annotation independently.

Summary

Java's built-in compiler annotations are lightweight, zero-runtime-overhead contracts between the developer and the compiler. @Override is the one that earns its keep most visibly - it converts "method name typo creates silent dead code" into "compile error immediately here," and every team's style guide should require it on every applicable method without exception. @Deprecated with since and forRemoval is how APIs retire gracefully in codebases large enough that removing something immediately would break too many call sites at once. @SuppressWarnings narrows a compiler warning to "I understand this specific case and accept the risk," but only works correctly when scoped tightly and named specifically. @FunctionalInterface protects the lambda-target property of an interface against future accidental breakage. @SafeVarargs is a specialist tool for generic varargs methods that need to declare their own safety to the compiler.

The thread running through all five is the same: each annotation gives the compiler information that the code's structure alone cannot express - intent that would otherwise live in comments or conventions, now machine-checkable and IDE-visible from the moment the source file is saved.

What to Read Next

Continue Learning Advanced OOP

Next Step

Custom Annotations

Learn how to create your own annotation.

→

Sealed Classes (Java 17+)

Learn how to restrict which classes can extend yours.

→

Object Cloning

Learn how to create a copy of an existing object.

→

protected Access Modifier

Learn how the protected modifier works across packages and subclasses.

→

←

PreviousAnnotations

NextCustom Annotations

→