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 👇
Top comments (0)