Building Software Libraries
- No service owner understands every package in their software.
- If there is a bug in your library, noticing the regression will be delayed after the release, as you don’t notice until somebody uses that release.
- Keep fewer codepaths (cyclomatic complexity)
- think about what other software might be running on service.
- You can explicitly version within package names to prevent against breaking changes, if you want to be super careful.
- Clients shouldn’t need to write boilerplate to use your library
- Libraries should be self-documenting - especially by throwing checked exceptions on edge cases.
- As a library owner, you have to be aware of any assumptions you’re making about the outside world.
- Once you release a library, you really don’t want to need to touch it, because you may break people.
- This means that you have to do a really good job at requirements gathering, and then don’t touch code unless it NEEDS to be touched.
- Be paranoid about changes to your package.
- Test your code with actual customers before releasing it publicly.
- You want to depend on as few packages as possible as a library, this makes it way easier to consume.
- Be cognizant about the logs and exceptions you spew, definitely log and except, but not too much.
- Link to wikis inside of exception messages. However, wikis can get out of date.
- Libraries should be: (Reliable, Intuitive, Secure, Efficient, Maintainable, Universal, Debuggable)
It is possible to create a service that is interacted with as a library, which is beneficial in some situations
- notes gleaned from a talk by Rob Atlas
Written on November 9, 2021