Optional vs null — Where Each Belongs

The short version: Optional for return types where absence is valid; null (with @Nullable) for everything else. This follows Brian Goetz's guidance — he designed Optional specifically for return types, not to replace null wholesale.

Where Optional belongs

• Method return types: findById, findByEmail, getConfigValue
• Chaining: opt.map(...).flatMap(...).orElse(...)
• Signaling 'might be absent' in public APIs
• That's it

Where Optional is WRONG

1. Fields

• Not Serializable — breaks JPA, Jackson, Java serialization
• Wastes memory — 24–40 bytes per Optional wrapper, millions = pressure
• No benefit to callers (they don't see the field)
• Use Discount + @Nullable, not Optional

2. Method parameters

• Forces callers to wrap: doWork(Optional.of(x)) is ugly
• Worse than just accepting null
• Better: overload methods or use @Nullable annotation

3. Collection elements

• List> is redundant — use List and filter nulls
• Map> — use Map, absence via key

4. Collection returns

• Return List.of() (empty), not Optional
• Empty collections are idiomatic in Java

5. Record components

• Same reasoning as fields — serialization issues

Anti-patterns to avoid

Return null from Optional method

• Defeats the entire purpose
• Callers still have to null-check
• Return Optional.empty()

Call .get() without guard

• Throws NoSuchElementException
• Use .orElseThrow(...), .orElse(...), .ifPresent(...), .map(...).orElse(...)

Optional.of(maybeNull)

• Throws NPE if argument is null
• Use Optional.ofNullable(...) for possibly-null sources

Better tools for non-return null handling

Nullability annotations

• JSpecify (new standard: Google/Oracle/JetBrains)
• JSR-305 (older: @Nullable, @Nonnull)
• Spring's @Nullable
• Compile-time / static analysis; zero runtime cost
• Flags mismatches in IDE, SonarQube, Error Prone
• Kotlin interop uses them

Objects.requireNonNull

• API boundary null checks
• Objects.requireNonNull(email, "email required")
• Fail-fast with clear message

Default values at construction

• Record compact constructors: nickname = nickname != null ? nickname : email;
• Builder pattern for many optional fields

Empty collection returns

• List.of(), Set.of(), Map.of()
• Better than null for 'no items'

Primitive Optionals

• OptionalInt, OptionalLong, OptionalDouble
• Avoid boxing overhead in hot paths
• Returned by IntStream.max(), .average(), etc.
• No map/flatMap; less ergonomic than Optional

The idiomatic flow

• Repository returns Optional
• Service unwraps with .orElseThrow, .map, .orElse
• Controller returns the User (or lets exception become 404)
• Fields in entities: just String email; (nullable if needed)
• Internal state: just null, maybe with @Nullable

Why not Kotlin-style non-null everywhere?

• Java's null is baked into JVM; can't banish
• Fields must be nullable for serialization, JPA, DI frameworks
• Accept it; use annotations and defensive checks

Recommendation: Follow the return-only rule: Optional is exclusively for method return types where absence is a legitimate outcome (repository finders, config lookups, parsing). Everywhere else — fields, parameters, collection elements, map values, internal state — use plain `null` with `@Nullable`/`@NonNull` annotations (prefer JSpecify for new code). Never return null from a method declared to return Optional; return Optional.empty(). Never call .get() without a guard; prefer .orElseThrow(...), .orElse(...), or .ifPresent(...). For collection returns, return empty collections (List.of()), never null. For hot-path primitives, use OptionalInt/OptionalLong/OptionalDouble to avoid boxing. Use `Objects.requireNonNull` at API boundaries for fail-fast null checks. Lean into Optional's chaining strength (.map().flatMap().orElse()) — this is where it shines over nested null checks. Don't try to eliminate null from Java entirely — that's what Kotlin is for; Java's job is to manage null pragmatically.