A List Apart

The A List Apart Blog Presents:

Brevity vs. Clarity

Article Continues Below

A few months ago, my good friend, Olivier Lacan, tweeted:

He rightly points out that a lot of commonly-accepted abbreviations exist only because a critical mass of people use them. We understand what “btn” means because we’ve seen it before, not because it’s a clear shortening of “button.”

Is the loss of clarity outweighed by the benefits of a shorter class name? In an era where most text editors provide autocompletion, three letters isn’t a huge difference from an authoring perspective.

Inevitably, someone else will come along someday and work with the code we write. Even if you work by yourself, future you will be a different person because of the work you’ve done and the experiences you’ve had between the times you focus on a project. Clarity is invaluable when others (or our future selves) come in to work on something—we don’t have to struggle to understand what is happening, we can get work done more efficiently, and the overall process will be much smoother.

On the technical side, brevity certainly has its place. The savings made by using a fewer letters each time a name is written can add up if your codebase is large enough. Better yet, minification and compression of CSS and JavaScript source files can save precious kilobytes and shorten page load times noticeably. There’s really no shortage of micro-optimizations you can find out there, all in the name of brevity and speed.

There are clearly good reasons for both approaches, so like most things in our work, it all comes down to how you decide what’s right for you and your situation. Is there a tangible, data-proven benefit of brevity? If not, be descriptive, expressive, and clear.

Hal Abelson and Gerald Jay Sussman said it best in their MIT Structure and Interpretation of Computer Programs course:

Thus, programs must be written for people to read, and only incidentally for machines to execute.

I let that guide me, but the lines between what’s for humans and computers can get blurry sometimes—JavaScript and CSS files are for both humans and machines, so it’s best to find a way to play to both sides’ advantages. Minification and compression are good tools here: clear source code for development, minified and compressed files for production.

No matter what, avoid abbreviating for abbreviation’s sake. The benefits of clear, readable code are almost always greater than typing fewer characters. And if brevity is applied thoughtfully in technical situations, you’ll use resources more efficiently, and that will make everyone happy.


11 Reader Comments

Load Comments