SimonComputing Logo

BLOG


Improving Developer Experience

Simon Woo

 on August 27, 2019 at 6:40 PM


This was originally written for a library we were building internally and we later realized the high level goals were useful for all library development, so here it is in a blog.

There is a lot of work being done for user experience, but the same level of attention has not been given to the developer's experience. Developers are users of libararies and tools, and while developers are
technically savvy, it doesn't mean that they wouldn't benefit from usability features in libraries that make their life easier.

An hour wasted on a misunderstood feature of a library multiplied over hundreds or thousands of developers is a lot of wasted time and frustration.

Developers that take the time to design libraries and APIs that are intuitive and easy to use can make a huge positive impact on the development community.

The following are specific areas of improvement in libraries.

Design the API First

Most developers are focused on the mechanics of getting something done. This often results in libraries where the client developer is having to sweat more details than needed to get the job done, because the library writers are very aware of every detail in the process. Instead, we need to step back and decide what details client developers really need to know and control to get the job done.

If we design the API first, we can define it for simplicity and ease of use. Without thinking about the mechanics of how to get the job done, it's more likely to include less unnecessary detail.

Things we can do to make the API easier to use:

  1. Design specifically for the simplest and easest way to get something done.
  2. Default values and reduce the amount of configuration needed to get up and running with the library.
  3. Allow access to advanced features for greater flexibilty, but don't require it.
  4. Document thoroughly. Make it clear what each feature will do and all side effects.
  5. Provide meaningful error messages targeted to the client developer. It is insufficient to provide messages that only you, the developer of a library can understand.
  6. Make it easy to debug. If there is too much abstraction, it is impossible to understand how to fix our problems.

Minimize Configuration Requirement

Many libraries give you a large number of configurable options, often with insufficient documentation to explain what the options do. One of the biggest barriers to using configuration options in a production environment is not havin a clear understanding of all the considerations and consequences of each option. It gets even more difficult when options are required but we don't understand what they do.

Other libraries give you very little control, but you are handicapped because you can't get what you want out of the library. It takes thought to balance these issues.

Making products highly configurable is often viewed as a good thing, but it also makes code complicated and the benefits of being configurable is often lost if it is difficult to understand the consequence of each configurable feature.

Configurable features should be thought through and added only when they provide recognizeable benefit over the complexity you'll add to the product. Fewer but well documented features is better.

Reducing Library Conflicts

Libraries make development faster, but as library developers, we can introduce opportunities for library conflicts for the client developer if we utilize a lot of libraries ourselves.

A common type of conflict comes from multiple parts of an application using the same library, but of conflicting versions. Each new library you add to your own library increases the chance of this type of conflict for your clients.

If a library is brought in for just one or two functions, it is often better to just hand code those functions and not bring in the library.

It is more work for the library developer, but it saves many client developers hours of heartache with dependency conflicts.

Reduce Conceptual Overload

Every new tool or coding concept is another thing developers need to learn to utilize your product and for developers to contribute to your project.

Think through whether you need to add more things that your client developers need to learn to use your product. If you have a new concept to introduce, make sure it provides worthwhile benefit over using one that already exists.

If you can build on concepts your client developers are likely to already know, they're likely to understand your library quickly.

A client developer is going to be more impressed with a library they are very quickly productive with than a library that uses esoteric concepts.

Create Model Code

Write high quality code that is a model for others to follow - code that is simple, easy to understand and worthy of imitation. Your code will be read by other people that will maintain it after you are gone. In open source, your code will be read by hundreds or thousands of developers, many looking specifically for examples to emulate.

Summary

Keep it simple.

Your library will contribute to creating a much better ecosystem of code that developers will enjoy using. You'll be part of a movement that will save developers hundreds of thousands of lost hours every year, and make the world better with your code.