JavaScript anti-pattern: self-documenting code

Recently, I’ve been thinking about few common anti-patterns I tend to see in professional JavaScript projects. Today, I wanted to talk about one of them: no docs.

A lot of more seasoned developers have this obsessed with “self-documenting code.”

And its true that if you write functions that do just one thing and follow logical naming conventions, what a piece of code does can often be pretty apparent.

Looking at the addItemToCart() function below, I can pretty quickly determine that I pass in the ID of the item to add, and it updates the quantity of that item in the cart object.

function addItemToCart (id) {
	if (cart[id]) {
		cart[id]++;
	} else {
		cart[id] = 1;
	}
}

But a little documentation can add a lot of good ergonomics for others working on the code base.

For example, let’s add a JSDoc header that defines what the id parameter is and the type of value it should be.

/**
 * Add an item to the cart
 * @param {String} id The product ID
 */
function addItemToCart (id) {

	// If the item is already in the cart, increase its quantity
	// Otherwise, add it
	if (cart[id]) {
		cart[id]++;
	} else {
		cart[id] = 1;
	}

}

In many text editors (including VS Code), anywhere that you use that function, hovering over it will pop-up a little modal that surfaces more information about it.

Even more important, though, is site/app level documentation.

A good README file adds a ton of value for anyone else working with a project (now or in the future). When I jump onto client projects, one of the first things I’ll do is create a README if one doesn’t already exist.

Things I like to see documented…

1. A Quick Start guide on how to run the site or app and see it working in a browser.
2. The architectural philosophy behind it. How is it built? What are the main tools powering it? Why were those choices made?
3. The project structure. How are the files organized and arranged. Sure, I can (usually) figure that out by digging through the code, but it’d be nice if I didn’t have to.
4. The tools and libraries that are used. If they’re third-party libraries, link to the docs. If they’re internal tools, include details on how they work.
5. How to run a build. What commands I need to run to turn source code into working code, run tests, and so on.

I think we as developers sometimes forget that the stuff in our heads isn’t the same stuff in everyone else’s brain, too. And even selfishly, what feels very obvious and apparent to you today might be a fuzzy distant memory after a few months or years away from a project.

Good documentation is an insurance policy for you and anyone else who has to work with the code base.