6 Designing a library

 

This chapter covers

  • Thinking about how to design a great library
  • Making beautiful interfaces
  • Being correct and avoiding unexpected behavior
  • Exploring Rust library ergonomics and patterns

This chapter marks the approximate halfway point in this book, so we’ll take a slight departure from the other content to discuss a subjective and somewhat controversial subject: what constitutes good library design. There’s no controversy about good design being better than bad design, but few people agree on what constitutes good. The zeitgeist of opinion surrounding good versus bad tends to shift and swing over time, which is important to consider for your designs.

The truth about good software design is that few universal rules exist. Much of what constitutes good is a matter of fashion, context, availability, and quality of tooling, as well as how the human–computer interface functions across these dimensions. That interface is the API of your library, and it’s the most important part of your library design.

In this chapter, we’ll explore some of the ideas, processes, and methods to consider when designing a library, with the goal of producing a library that’s easy to use, delightful to work with, difficult to use incorrectly, and flexible enough to solve a wide variety of problems. We’ll use an example from earlier in the book to build our library.

6.1 Meditate on good library design

6.2 Do one thing, do it well, and do it correctly

6.3 Avoid excessive abstraction

6.4 Stick to basic types

6.5 Use the tools

6.6 Good artists copy; great artists steal (from the standard library)

6.7 Document everything, and provide examples

6.8 Don’t break the user’s code

6.9 Think of the state

6.10 Consider the aesthetics

6.11 Examining Rust library ergonomics

6.11.1 Revisiting linked lists

6.11.2 Using rustdoc to improve our API design

6.11.3 Improving our linked list with more tests

6.11.4 Making our library easier for others to debug

Summary