Posts Tagged ‘APIDesign’
[KotlinConf2024] Why We Can’t Have Nice Things in Kotlin: Library Challenges
Vsevolod Tolstopyatov, a Kotlin libraries team member at JetBrains, entertained KotlinConf2024 with a witty exploration of why Kotlin’s standard libraries evolve slowly. From Turkish locale bugs breaking compilers to time zone quirks skipping entire days, Vsevolod revealed the hidden complexities of API design. Through anecdotes like Twitter polls on naming and a friend’s missed alarm, he highlighted how human language, historical quirks, and real-world constraints challenge library development, urging developers to appreciate the slow, thoughtful process behind robust APIs.
Human Language: The Turkish I Debacle
Kotlin’s string functions, like toUpperCase and toLowerCase, rely on system locales, leading to unexpected issues. Vsevolod recounted a bug where code compiled in Turkey failed due to the Turkish dotted and dotless I. Uppercasing an English lowercase i in Turkish yields a dotted uppercase İ, breaking method names like intArray. This forced the deprecation of locale-dependent functions, replaced with uppercase and lowercase using a root locale. The lesson: human languages’ diversity demands careful API design to avoid breaking code across cultures.
Naming Woes: The Capitalize Conundrum
Naming APIs is deceptively hard. Vsevolod shared how the deprecated capitalize function lacked a clear replacement because “capitalize” means different things to different developers. Twitter polls revealed no consensus, and other languages like Python and Ruby use capitalize inconsistently. With all good names taken or ambiguous, Kotlin’s team struggles to craft intuitive APIs without confusing users. This naming challenge slows library updates, as new functions risk misinterpretation or overlap with existing conventions.
Time Zones: Samoa’s Missing Day
Time zone complexities plague datetime APIs. Vsevolod described a case in Samoa, which skipped December 30, 2011, to align with Australia’s time zone, jumping from UTC-10 to UTC+14. A simple date addition (e.g., December 29 + 2 days) yields inconsistent hours due to the missing day. Adding time zone parameters fixes this but complicates APIs, especially on devices crossing time zone boundaries, like aircraft. These real-world quirks force Kotlin to balance simplicity with correctness, often at the cost of elegance.
Daylight Saving Time: Bug Hunting’s Legacy
Daylight saving time (DST) adds further headaches. Vsevolod traced DST to George Hudson, a 19th-century entomologist who proposed time shifts to hunt bugs in New Zealand. During DST transitions, times like 2:30 AM may not exist (spring forward) or occur twice (fall back), breaking datetime calculations. An anecdote about Vsevolod’s friend Vlad, whose smart home set a 9:30 AM alarm instead of 8:30 AM during a DST shift, underscored the need for explicit API parameters to handle ambiguous times, sacrificing simplicity.
API Design: Slow and Steady Wins
Vsevolod concluded that Kotlin’s libraries evolve slowly to avoid mistakes. Rushed APIs lead to bugs, like Vlad’s missed alarm, requiring years of maintenance. Thoughtful design, considering edge cases like locales, time zones, and DST, ensures reliability but delays releases. Twitter polls and community feedback help, but the real world’s complexity—political, historical, and cultural—demands patience. By prioritizing robustness, Kotlin’s team crafts APIs that won’t “get anyone fired,” even if it means fewer “nice things” per release.
Links:
[DotJs2024] API Design is UI Design
In the intricate tapestry of software craftsmanship, the boundaries between visual interfaces and programmatic ones blur, revealing a unified discipline rooted in empathy and usability. Lea Verou, a luminary in web standards and W3C TAG member, delivered a revelatory session at dotJS 2024, asserting that API design mirrors UI design in every facet—from intuitiveness to error resilience. With a PhD from MIT focused on developer experience and stewardship of dozens of open-source projects, Verou dissected the pitfalls of APIs that frustrate and the principles that enchant, urging creators to treat code as an interface wielded by fellow humans.
Verou opened with a visceral anecdote: the SVG DOM’s labyrinthine quest to extract a circle’s radius, yielding not a crisp number but an SVGAnimatedLength riddled with baseVal, animVal, and unit-conversion methods—annoying even sans animations. This exemplar encapsulated her thesis: APIs, be they functions, classes, components, or native browser APIs, are user interfaces where developers are the users, and interactions manifest as keystrokes. Echoing Alan Kay’s maxim—”simple things should be easy, complex things possible”—she mapped it to a complexity plane: low-effort dots for trivial tasks, viable paths for sophistication. Usability tenets, from Google Calendar’s drag-and-drop simplicity to advanced recurrence rules, permeate both realms; DX is merely UX recast for code scribes.
Central to Verou’s discourse was user-centricity: APIs thrive when attuned to genuine needs, not theoretical purity. High-level use cases—like assembling IKEA furniture with a screwdriver—inform broad abstractions, while low-level ones—like screwing a wall anchor—demand primitives. She critiqued legacy DOM traversals burdened by redundant parent references, supplanted by modern APIs favoring single-truth sources. Components exemplify elegance: encapsulating dialog boilerplate into reusable units slashes cognitive load. Iterating isn’t prohibitive; ship high-level facades covering 80% of scenarios, layering primitives as demands surface—or vice versa, observing usage to scaffold abstractions. The Intl.DateTimeFormat API’s evolution—from vague toLocaleString to nuanced options yielding structured outputs—exemplifies this progressive disclosure, smoothing from casual to granular control.
Verou championed empirical validation: user testing, sans visuals, via representative tasks and think-aloud protocols. Five participants unearth 85% of issues; two halve them. Zoom suffices—no labs required. Dogfooding complements: prototype demos, draft docs, author tests pre-implementation, refining iteratively. Empathy crowns all: intuit users’ pains, infer principles organically. Tailwind’s rise signals CSS’s accessibility gaps; blame the medium, not the maker, and mend it. Verou’s clarion call: infuse humanity into APIs, easing burdens and amplifying creativity across the dev spectrum.
Usability Principles Across Interfaces
Verou wove Kay’s dictum into a visual quadrant, plotting task complexity against UI/API effort, advocating coverage of simple-easy and complex-possible quadrants. User needs—pain points, scenarios—drive this: distinguish macro goals from micro actions, ensuring APIs mirror real workflows. SVG’s unit obsessions ignored 90% of queries; streamlined getters would suffice. Progressive layers, as in date formatting’s escalating options, democratize power without overwhelming novices.
Empirical Refinement and Empathy
Testing APIs demands observation: task users, query struggles non-leadingly, affirm it’s the design under scrutiny. Verou debunked myths—engineers aren’t users; widespread misuse indicts the API. Dogfood rigorously: sketch code flows pre-build, iterate via docs and tests. Ultimate imperative: cultivate care—empathize with wielders’ contexts, yielding designs that intuit, adapt, and inspire.