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

  1. When writing LESS I always keep classnames as short as possible, adding a comment above the selector, where I explain what element it’s is addressing.
    The CSS file for debugging keeps all comments and the CSS file for production is minified and all comments are stripped.

    That way any developer knows what he or she’s looking at when scanning through the LESS files or the unminified CSS, while in a live-environment the machine gets an optimized file.

    EDIT: Funnily enough, I’ve never used .btn though.

  2. You asked, “Is there a tangible, data-proven benefit of brevity?”

    Shorter served files save bandwidth and speed page load. Use short names everywhere, but document and comment them. Use tools to minify and strip comments. That said, one less image will almost always save more bandwidth than minification, so always ask yourself “Is that image necessary?”

  3. @Marco, if you have to add comments to explain where you’re using a class, it’s probably a bad class name. If you use something like BEM, then you should be able to tell what you’re styling by the class name alone.

  4. The primary goal of abbreviating names, to me, isn’t optimisation or anything machine-related (as pointed out there’s plenty of tools to handle that); it’s just… readability. When abbreviations are common and understood, I find them just as clear as the full words yet with fewer signs for the eye to parse.

    I agree the “common and understood” bit is where problems usually lie, but in most contexts there’s definitely room for a few helpful abbreviations (for example, `err` or `val` shouldn’t surprise anyone used to reading Javascript).

  5. This falls into the premature optimization and sometimes over-optimization bucket. I find developers who have pulled all the vowels out of classnames rcvdTpHdr or lstPtntSmmry or other nonsense under the guise of “but it’s smaller!”

    You should only optimize to the level necessary for the requirements of your site and for reasonable near future targets. Otherwise your focus should be maintainability. Example: If the client says “I want a <4 second load time" then define that and optimize to just below that level if you can. That's your real target, because the client didn't say "can you take all the vowels out of your code and obfuscate it so we can save 1k off this page"

    I've seen too many sites attempt to optimize the little bits like this, shortening classes and id's, worrying about selector performance, arguing ad-nauseum about XSLT vs JSP rendering performance metrics on a 2gb test file, and then completely failing to understand why a 500k of images, a 500k (invalid) HTML file, with 20+ scripts and 15k lines of CSS code, hooked to an outdated mainframe isn't exactly giving users the warm and fuzzies.

  6. I’ll offer that it (btn) is more readable when scanning based on the fact that there is a ‘button’ element, so the difference between .button and button isn’t as clear as it is between .btn and button.

    There is no html element large (so no clash there, though there is small so does sml get used I wonder?), I don’t use frameworks myself currently so without doing research myself I can’t offer suggestions on any other such conventions.

  7. Abbreviation is a cancer that tends to spread. I count seven abbreviations in the following, which any Unix sysadmin can read, but which makes no sense to nearly anyone else:

    ls -lf /var/lib /usr/local/bin

  8. I really can’t believe this sort of thing is still being debated when I thought this was cleared up once and for all by P. J. Plauger in the Elements of Programming Style in the early 1970’s.

    I don’t use CSS or JavaScript but I would have thought the “source” code would be optimized (and obfuscated) by removing comments and renaming long variables before being placed on a live server.

    In brief: very short or cryptic identifiers make code hard to understand. In my experience (compiled languages) the problem is with excessively long identifiers – see my blog:

Got something to say?

We have turned off comments, but you can see what folks had to say before we did so.

More from ALA