Kotlin API Design

Kotlin API Design That Ages Well: What Your Interfaces Won't Tell You Stable kotlin api design breaks in a specific way: not at the commit where the problem was introduced, but weeks later, in someone else's module, on a release nobody planned for. The code looked right. The diff was clean. But the real problem with Kotlin API Design is the gap between what the source shows you and what the JVM actually executes — and that's exactly where public contracts quietly fall apart. Default Arguments and the Bitmask You Never Wrote Kotlin default arguments binary compatibility is one of those issues that feels impossible until you see it once. Under the hood, the compiler doesn't just emit the function you wrote — it also generates a synthetic $default overload that reconstructs missing arguments using a bitmask. That overload has its own JVM signature. Add a new optional parameter, and the signature changes. Modules that compiled against the old version now reference a method that doesn't exi