Comments on Brevity vs. Clarity

11 Reader Comments

Back to the Post
  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.

    Copy & paste the code below to embed this comment.
  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?”

    Copy & paste the code below to embed this comment.
  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.

    Copy & paste the code below to embed this comment.
  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).

    Copy & paste the code below to embed this comment.
  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.

    Copy & paste the code below to embed this comment.
  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.

    Copy & paste the code below to embed this comment.
  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

    Copy & paste the code below to embed this comment.
  8. Nice to see a plea for clarity from a man named Lacan ;)

    Copy & paste the code below to embed this comment.
  9. Here’s why btn is preferred
    http://jqueryuk.com/2015/videos.php?s=mdo-ular-css
    (see minute 4:35)

    Copy & paste the code below to embed this comment.
  10. 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: http://devmethodologies.blogspot.com.au/2012/04/long-identifiers-make-code-unreadable.html

    Copy & paste the code below to embed this comment.
  11. Fascinating - really enjoyed reading this.

    Copy & paste the code below to embed this comment.