Let's talk about a topic under the subject of DX that I call "code usability". When you create an API for a module, its usability can have a huge impact on productivity. I identified what makes code easy for me to use and came up with my 3 "ease of use" levels.
In the following JavaScript 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 type checking and error handling
Example:
Takeaway
Unfortunately, the APIs we use don't always reach level 3. Try using a library with lackluster documentation, or a web service that responds with vague error messages, and it can cost you hours. So, how can you write usable code? Well in JavaScript, for example, 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 👇
Top comments (0)