Writing a Java library with better experience

Video: https://www.youtube.com/watch?v=0eQbsVLxmMk

It is fun to write a library or a framework. It allows us to play with many interesting ideas that were not possible before due to the constraints in others' work. However, utmost care must be taken to build it great.

In this session, Trustin Lee, the founder of Netty project and Armeria, shares you the opinionated key practices from his recent works which might be useful when you build your own library or framework, or even designing an API for your project.

Previously presented at:

- JPoint in Russia on July 2, 2020
- LINE Developer Days in Japan on November 27, 2020

Transcript

1. @trustin Trustin Lee, LINE Jul 2020 Writing a Java library with better experience Writing a Java library with better experience
2. @trustin A three-part session • Core principles • Tips & tricks – Mostly Java-specific – Applicable to other languages • How to nurture the community – … for mutual benefit of users & yourself – May seem less important but is a crucial part
3. @trustin Where this came from – 23.6k 100 – netty/netty – @netty_project – 2.6k 111 – line/armeria – @armeria_project
4. @trustin Core principles
5. @trustin Be in user’s shoes • What will user’s code look like? • Imagine the best possible user code for the core problem. – Type like the API is already there. – Forget about how you’ll implement it. • Keep refining while adding increasingly complex use cases. • Reach a certain level of confidence first. – Keep in mind – This is not a sprint but a journey. – No need to implement anything until ready.
6. @trustin Consistency • ‘A’ is like this. Why is ‘B’ like that? • Consistency in your API – e.g. This builder accepts long, but this accepts Duration. • When in doubt, check others’ work: – Language SDK’s API • JDK, Kotlin SDK, … • Don’t follow blindly. – Different context, new trends, mistakes, ... – Other popular libraries • Guava, Spring, …
7. @trustin Cognitive load · Learning curve • Start with a small set of concepts. • Build more complex solutions on top of them. • Use familiar constructs – Builders and factories – Decorators and strategies – (Functional) Composition • Don’t expose too much at once. – e.g. 10 overloaded builder methods
8. @trustin User experience ≫ Internal complexity • Always choose UX. – Good UX is crucial for the virtuous cycle of project. • Can tame internal complexity, but can’t tame poor UX: → Confused users → Too many support tickets → Poor experience · Less time for dev → → Low-quality feed back · Burnout → Fix not at its best form → … • API with good UX often leads to better implementation: – Encapsulation → More freedom at implementation level – Composition → Less complexity at implementation level
9. @trustin Tips & tricks
10. @trustin Use Java, not other languages • Non-Java library means: – Additional (BIG) runtime dependencies – Weird synthetic classes and methods – Lang A → Java & Lang B → Java may be easy, but Lang A → B may not. • Keep the core in Java • Provide language-specific layers, e.g. DSL – Use others’ help if you are not good at those languages.
11. @trustin Keep core dependencies minimal • Don’t depend on another framework • Let people choose – … by providing integration layers • Spring Boot, Dropwizard, … • Shade utility dependencies – Guava, Caffeine, FastUtil, JCTools, Reflections, … – Use ProGuard to trim unused shaded classes: 30 MB → 6 MB – Be aware of licenses
12. @trustin Go non-null by default • Use @Nullable. – Do not use j.l.Optional. • A language has its own null handling: – Option (Scala) – Nullable types (Kotlin) • The caller can wrap the result: – Optional.ofNullable() – Option() • Escape analysis doesn’t always work. class Server { … @Nullable ServerPort activePort() { … } … } class CacheControlBuilder { … CacheControlBuilder maxAge( @Nullable Duration maxAge) { … } … }
13. @trustin @NonNullByDefault in package-info.java /** * Indicates the return values, parameters and fields are non-nullable by default. * Annotate a package with this annotation and annotate nullable return values, * parameters and fields with {@link Nullable}. */ @Nonnull @Documented @Target(ElementType.PACKAGE) @Retention(RetentionPolicy.RUNTIME) @TypeQualifierDefault({ ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD }) public @interface NonNullByDefault {}
14. @trustin Nullness annotation libraries • javax.annotations (jsr305) – Most popular – Not compatible w/ Java Modules • jspecify – Joint effort to replace jsr305 – Too soon too tell • JetBrains annotations – IDE support – Contract annotations • @Contract("null -> null") • Checker framework – Mature – More than just annotations
15. @trustin Validate early with message • Which stack trace is easier to understand? java.lang.NullPointerException: idleTimeout idleTimeout at java.util.Objects.requireNonNull() at com.linecorp.armeria.server.ServerBuilder.idleTimeout() idleTimeout() at com.linecorp.armeria.server.ServerTest$1.configure() java.lang.NullPointerException: null at com.linecorp.armeria.server.ServerBuilder.initSocket() initSocket() at com.linecorp.armeria.server.ServerBuilder.build() at com.linecorp.armeria.server.ServerTest$1.configure()
16. @trustin Think cognitive load • Raise an exception as soon as a bad value is given. – e.g. Don’t validate builder properties at build() • Provide a meaningful message – What is null? • Use Objects.requireNonNull() – Why is this bad and what is good? • Use Preconditions.checkArgument()
17. @trustin Consistent exception messages • NullPointerException – “paramName” • IllegalArgumentException – “paramName: badValue (expected: goodValueSpec)” • idleTimeoutMillis: -1 (expected: >= 0) • filePath: ../my_file (expected: an absolute path) • Choose what works for your project – … but the messages should be consistent and meaningful.
18. @trustin import static com.google.common.base.Preconditions.checkArgument; import static java.util.Objects.requireNonNull; public final class ServerBuilder { … public ServerBuilder port(ServerPort port) { ports.add(requireNonNull(port, "port")); return this; } public ServerBuilder http2MaxStreamsPerConnection( long http2MaxStreamsPerConnection) { checkArgument( http2MaxStreamsPerConnection > 0 && http2MaxStreamsPerConnection <= 0xFFFFFFFFL, "http2MaxStreamsPerConnection: %s (expected: a 32-bit unsigned integer)", http2MaxStreamsPerConnection); this.http2MaxStreamsPerConnection = http2MaxStreamsPerConnection; return this; } … }
19. @trustin Static factory methods over constructors • Easier to hide implementations • More naming options – of(), ofDefault(), empty() • Chaining to a builder – CorsService.builder(String... origins) – CorsService.builderForAnyOrigin() • Optimization opportunity – Create an instance of different type for different parameters
20. @trustin public interface EndpointGroup extends … { static EndpointGroup empty() { // StaticEndpointGroup is package-private. return StaticEndpointGroup.EMPTY; } static EndpointGroup of(EndpointGroup... endpointGroups) { requireNonNull(endpointGroups, "endpointGroups"); // Highly simplified pseudo code // that shows how a static factory can optimize: switch (actualNumberOfEndpoints) { case 0: return empty(); case 1: return endpointGroups[0].first(); default: // CompositeEndpointGroup is package-private. return new CompositeEndpointGroup(endpointGroups); } } … }
21. @trustin Avoid inner classes • SomeClass.Builder – Whose “Builder” is it? – What happens if we import OtherClass.Builder? • It’s dev-centric to organize the builder impl in the same class. – User experience ≫ Internal complexity import com.example.SomeClass.Builder; Builder builder = SomeClass.builder();
22. @trustin Avoid code generators in public API • e.g. Lombok – Sometimes OK for generating internal classes, though. • Public API requires a lot more human touch – Even a simple getter · setter needs hand-crafted Javadoc • When this method should be used • The default value when unused • Examples • Often lowers the contribution barrier if not used
23. @trustin public final class CookieBuilder { /** * Sets the <a href="https://tools.ietf.org/...">{@code SameSite}</a> * attribute of the {@link Cookie}. The value is supposed to be one of * {@code "Lax"}, {@code "Strict"} or {@code "None"}. Note that this * attribute is server-side only. */ public CookieBuilder sameSite(String sameSite) { this.sameSite = validateAttributeValue(sameSite, "sameSite"); return this; } } Hand-crafted setter in action
24. @trustin Follow semantic versioning • Major bump → Breaking ABI changes – Dropping a new version of JAR may fail. • Minor bump → New features – May add new classes – May add default or static methods – May add methods to final classes • Micro bump → Bug fixes – No public API changes • It’s hard to follow semantic versioning strictly. – Experiment as much as possible in 0.x.y days. – Use tools such as JDiff Version 1 1.3 3.2 2 <major major>.<minor minor>.<micro micro>
25. @trustin Keep public API to minimum • Think twice before adding ‘public’ or ‘protected’. – Hide implementations and use static factory methods in interface. – If not possible because of inter-package references: • Move to the ‘internal’ packages. • Can be hidden or deprioritized by tools at least – Javadoc, IDE, … • Why? – API change often requires a major version bump. • Nobody likes breaking changes… – Implementation detail changes often in reality – bugs, performance, hindsight, …
26. @trustin Make your classes & methods final • Prefer composition over inheritance. – Accept Function, Consumer, Predicate, … • Why? – User mistakes: • Forgets to call super, Performs something totally unexpected – Good balance between UX and DX (developer experience) • Discuss · Think a lot before removing final (= opening a can of worms!) – Users can often fork a problematic class. • Of course, you can provide some abstract classes.
27. @trustin Use API stability annotations • A new feature sometimes needs time to mature. – Use API stability annotations to balance between velocity & stability. • Choose what works best for your community. – @Beta, @UnstableApi, @InternalApi, @MaturityLevel… – Apache Yetus audience annotations – @API Guardian • Don’t overuse it, though.
28. @trustin Usual engineering tips • Prefer immutability. • Implement toString() properly. • Write awesome Javadoc · documentation. • Keep your code clean – Consistent and beautiful code style – Technical debt must be handled on time. • Automate for less tedium & higher quality: – Formatting, linting, static analysis, test coverage, release process, …
29. @trustin Community growth
30. @trustin Don’t give up • It usually takes (long) time – years, not months • Dogfood and keep improving, because people don’t use when: – Stale activity • e.g. No releases, commits or site updates in last 6 months – Poor metrics • e.g. No test coverage, build failures, … – Poor documentation • No need to write a book, but should be good enough to get started
31. @trustin Get the most out of interaction • Set up a place to chat informally. – e.g. Slack, Gitter, … • Respect and appreciate. – Everyone is not good at textual communication. – Every single visitor is important especially at the early stage. • They could be your first customer or colleague! • Engage proactively. – Create a new issue to detail the reported problem · feature · workaround. • They will usually be happy to provide feed back, or even a pull request.
32. @trustin
33. @trustin Don’t be shy but ask questions • How did you find us? • What features do you like about us? • What is missing? What could be added or improved? • Are you using it in your product? – If so, how? If not, what would help you decide? • I created an issue for you. Do you have anything to add? • Are you interested in sending a pull request?
34. @trustin Usual soft skills • Be thankful. • Assume good faith. • Don’t take it personally. • You sometimes need to agree to disagree. • Humors, emojis and GIFs • Be careful of burnout.
35. @trustin You need a web site • README.md is not enough. – Aesthetics matter! – No room for elevator pitch – Not always mobile friendly – No traffic analysis • Find the site generator that works best for you. – Gatsby, Hugo, Sphinx, Jekyll, … – https://www.staticgen.com/
36. @trustin
37. @trustin Keep your eyes on “Referer” logs • Who wrote about us? • Who is using us? • Engage! – Let users know we care and appreciate. – Update the ‘community resources’ page. – Ask questions. – Tweet about it. – Propose a better way to use.
38. @trustin
39. @trustin Prepare a good dev guide • Today’s user can be tomorrow’s dev in a library. • Spend your time for good onboarding experience. – Build requirements & How to build – How to set up with IDE – Conventions, e.g. Checkstyle rules – CLA (Contributor License Agreement) – https://cla-assistant.io/ • See https://armeria.dev/community/developer-guide for an example.
40. @trustin If you have more time… • Speak in conferences. – https://www.cfpland.com/ • Host contributor events. – e.g. Open source coding sprint – Try with your colleagues at work first. • Watch and learn, or let’s work together! – https://github.com/line/armeria – https://github.com/netty/netty
41. @trustin Meet us at GitHub ARMERIA.dev github.com/line/armeria