Code Usability and my "Ease of Use" Levels

In my experience, the concept of "code usability" doesn't get enough attention. When you create a library or module, its usability can have a huge impact on the consumer's productivity. I identified what I find makes code easy to use and came up with these 3 "ease of use" levels.

DISCLAIMER: These are just my ideas, not "official" by any means.

In the following examples, imagine we're using a geometry library, and we want some way to represent a pyramid shape in our code.

Level 1: Easy to use

You can easily figure out how to use it by reading documentation or examples.

✔️ Simple
✔️ Well-documented

Example:

---

Level 2: Intuitive to use

You can guess how to use it without reading documentation, usually based on function, class, or variable names.

✔️ Good naming

Example:

---

Level 3: "Uses itself"

You can use it without even thinking about it, usually with code assist (intellisense). It also prevents you from misusing it by mistake.

✔️ Facilitates code assist
✔️ Thorough error handling

Example:

---

Takeaway

Sadly, level 3 isn't always a given. Try using a library with lackluster documentation, or accidentally forget a required argument, and it could set you back hours. So, how can you write usable code? Well in JavaScript, you can get pretty far with good JSDoc comments.

Example:

/**
 * Returns an object representing a pyramid with the given dimensions.
 * @param {number} length
 * @param {number} width
 * @param {number} height
 * @returns {{length: number, width: number, height: number, volume: () => number}}
 * @example
 * const p = createPyramid(2, 3, 4)
 * const v = p.volume()
 */
export function createPyramid(length, width, height) {
  return {
    length,
    width,
    height,
    volume() {
      return (length * width * height) / 3;
    },
  };
}

The rest comes down to your design decisions. Try putting yourself in the shoes of the consumer, and test if your code reaches level 3. You may be surprised how much you can help the future consumer... even if it ends up being YOU.

💬 Feedback/criticism are welcome below 👇