There are two kinds of Hungarian Notation. “Systems” Hungarian ascribes a type to a variable, typically in a language that does not have strong typing, and “Apps” Hungarian appends to the variable name a dimension of intent. In a nutshell, one is to be avoided and the other lives on as namespacing.

If you’ve ever had to muck about with very old code, you may have seen variables such as strFirstName or intProductCount. I first ran across this when I was first discovering programming in VBA (yuck). It sort of made sense to my newbie mind. When I later learned Java in a college course, System Hungarian became worse than useless. The type is already enforced by the language, so int intProductCount is obviously redundant and creates manual work during refactoring. It is largely accepted throughout the programming community that Systems Hungarian notation is an antipattern, but it is slightly less widely known that this “bad” implementation of Hungarian notation is not what the creator envisioned at all!

Apps Hungarian, on the other hand, is the “real” Hungarian notation, and it’s very good! It attempts to communicate something about the purpose of the variable. Where Apps Hungarian was meant for programming languages, it applies anywhere you need to name something. The principle applies to HTML/CSS classes, too. Consider the following code:

1
2
3

<div class="search field space">
    <input ...>
</div>

You can take a guess at what those classes mean, but you probably won’t be very confident! What if the classes were named like this:

1
2
3

<div class="js-search c-field, u-space">
    <input ...>
</div>

With just a little knowledge of your project’s conventions, you now know that js-search is a hook for javascript, c-field is the root of the “field” component, and u-space is a utility class for slapping on additional styles, probably just margin and/or padding. That’s the benefit of Apps Hungarian. To me, Hungarian notation is nothing more than the first implementation of today’s concept of namespacing, which is one high-impact method for promoting good CSS architecture. Perhaps there’s a distinction between the two terms, but indisputably the aim of both is to communicate intent.

Here’s a twelve-year-old post from Joel Spolsky that is both amusing and more informational than my own li’l blog post.

Well, I did it. I finished the architectural guidelines.

As far as I know, I’m the only one who uses it. Or is even aware of its existence. Working in isolation from the rest of the company has its benefits, but also its drawbacks.

I’m not yet an expert on front end development, so I am sure that my guide is lacking in several fronts. I suspect that the beginning is too verbose; I wrote it partly as an exercise in apologetics for explaining the benefits of such guidelines to my colleagues. The actual guidelines can be summarized very simply (and loosely in order of importance):

• Use a naming convention like that of SUIT CSS or BEM.
• Use a component methodology like SMACSS, SUIT, or BEM. This is key
• Use selectors of specificity 0,0,1,0 (a single class selector).
• Use namespaces to separate classes based on purpose (modules, script hooks, integration testing, frameworks, state management, etc).
• Know when to break away from the component methodology. It will only help you 90% of the time.
• Document your components in a pattern library.
• Organize related CSS and JS files in the same directory, or in symmetrical directory structures.
• Order every HTML elements’ attributes: id, class, and then everything else.

The full guidelines, as cringe-inducing to my future self as I’m sure they’ll be, can be found here. I learned a lot putting this together. Not only did I learn the subject matter, but also about how difficult it can be to write good documentation on topics of a less objective nature.

I’ve been tasked with creating “CSS Architecture Guidelines” at work. I’m very excited to work on this, both because I love CSS development and because it’s an increase in responsibility and trust that my managers are extending to me. This post is a short survey of that work-in-progress; a full documentation might be forthcoming and published on GitHub (if they let me have my way).

I’ve written about JavaScript style before, but that is a hot arena with a lot of competing schools of thought. There’s not much of the same in CSS. There’s a famous poll about how most CSS developers organize their rules; that’s probably the most contentious code style issue in CSS, and I’ve never heard anyone argue for one over the other with the same zeal that some argue for tabs versus spaces (I suppose that’s also an issue in CSS files, but CSS devs don’t seem to care).

This architecture document does not concern code style as much as how to develop good, reusable CSS and file organization. SMACSS has been hugely beneficial to me, who had never been exposed to any system of CSS development. I’ve learned a little bit about Atomic CSS, OOCSS, and BEM. I’m currently reading through Enduring CSS, and I plan to delve deeper into SUIT CSS next. Regarding code style, my reference documents are shorter: Google HTML/CSS style guide, Idiomatic CSS, and the CSSLint rules.

There are a bunch of things that are obviously good and fairly certain to be included in the architecture guidelines. Other things are either uncertain, or would be good but would involve refactoring our existing projects. There’s a collaboration aspect to this work; I can’t simply mandate architectural rules. Getting buy-in from the other developers, particularly those working on other projects, has been a good challenge to develop my soft skills.

This is due by the end of 2016 Q2, so I have five more weeks to finalize everything. I hope to publish everything by then.

A long-sh absence of two months is due to me taking on a new position that actually pays money! After five months of being on sabbatical, I finally realized how nice it is to have cash flow.

Anyway, I’d like to share the monumental project I’ve been undertaking for my employer (whose opinion I do not represent in any capacity; my words are my own; etc, etc). When I started there, they lacked the manpower to transition from an early CSS framework called Skeleton, which, to be honest, is not bad! But 1: it does not support IE8, which we are committed to doing for grudgingly legitimate reasons, and 2: our web site has grown into a big product, so Skeleton’s minimalism is not suitable for our web site. So I set about figuring out how to transition.

We had plenty of pages built on* skeleton. We wanted to build new pages on Bootstrap. But the most challenging requirement is that we wanted to use Bootstrap in the header and footer of every page (but not the body) to trigger Bootstrap modals. In effect, we needed both frameworks on existing pages, and we needed them to not conflict.

* (In actuality, skeleton.css loaded after our custom styles. There are, no doubt, specificity battles because of this unfortunate fact.)

Less to the rescue! Less is a CSS preprocessor that allows us to treat CSS more like code and less like markup. (Although I prefer Stylus for its flexible syntax and more powerful functions, Less was already established in my organization). Using Less, I was able to easily prepend a class to every single rule in Bootstrap. This:

1
2
3
4
5

.container {
    .inner {
        color: blue;
    }
}

evaluates to:

1
2
3

.container .inner {
   color: blue;
}

so this:

1
2
3

.bootstraptransition {
    @import "../../lib/bootstrap";
}

evaluates to this:

1
2
3
4
5
6
7
8
9
10
11
12

...
@media (min-width: 1200px) {
    .bootstraptransition .container {
        width: 1170px;
    }
}
...
.bootstraptransition .row {
    margin-right: -15px;
    margin-left: -15px;
}
...

This allowed me to apply bootstrap only to specific elements on the page. However, this introduced a problem. Every rule increased its specificity by 0|0|1|0 (learn about specificity interactively). This means that in the element<div class="col-md-4 myclass"> the bootstrap rule .bootstraptransition .col-md-4 would override .myclass, regardless of load order. The solution is to also elevate every single custom rule with the transition class.

1
2
3
4

.bootstraptransition {
    @import (less) "../../css/styles.css"; 
    // the `(less)` bit interprets .css as .less
}

The benefit of this entire approach is that it enables us to scope Bootstrap to segments of the page, thus overriding another framework that uses the same class names.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<body>
    <nav class="bootstraptransition">
        <p>This content is Bootstrapped and overrides Skeleton.<p>
        <div class="container">
            ...
        </div>
    </nav>
    <section>
        <p>This content is bootstrap-free and uses Skeleton.<p>
        <div class="container">
            ...
        </div>
    <section>
</body>

The downside is that every single css rule is now bloated with an extra class, but gzip can probably handle the repetition (and in any case, this is the cost of running two frameworks on the same page, and an excellent reason for management to allocate enough time to transition fully to the new framework). Another downside is that we now have to manage bootstrap-skeleton overrides. Given the following CSS:

1
2
3
4
5
6
7
8
9
10

/* bootstrap-transitional.css */
.bootstraptransitional .classname {
    margin: 0;
}

/* styles-transitional.css */
.classname {
    margin: 20px;
    border: 1px solid black;
}

the span in <div class="bootstraptransitional"><span class="classname">Hello</span></div> will have margin 0, but it will also have the unwanted border. To solve this problem, enter override-transitional.css. This file is loaded after both bootstrap-transitional.css and styles-transitional.css in order to “reset” only those things that need to be reset because of the existence of a second, unwanted framework.

1
2
3
4

/* override-transitional.css */
.bootstraptransitional .classname {
    border: none;
}

Why not just put border: none; in bootstrap-transitional.css? Because we are looking forward to one day ditching Skeleton altogether. Separating these rules into a new file will let us simply delete it when the transition is complete. Otherwise, we’d have to go digging in bootstrap-transitional to remove a ton of little resets that will be obsoleted in the absence of Skeleton.

So there you have it. A method for making two frameworks play nice. It works, it’s in production, and it took me a month to pull it off while simultaneously handling a full load of actual development.

I was reading a list of things a programmer does. Lists usually don’t repeat themselves; each item is unique. So I became very confused when I read two consecutive items: “documentation” and “commenting your code.” I looked back and forth in bewilderment, trying to figure out why there were two identical items in the list. Of course, the letters are very different, and one item had three words while the other had only one.

I finally realized my mistake, and became quite pleased with myself that I consider these two things so intrinsically related that they defaulted to being the same thing in my mind. After all, we’re all trying to achieve that great ideal called “self-documenting code.” The more I thought about it, however, the less sure I was that this was a good mental association.

I can’t deny the usefulness of formal documentation, especially when I have needed to use some library whose source code I do not care to examine. And I’d love to always write code that perfectly communicates the code’s purpose and reason for existing. But I have struggled enough with trying to name things, and with human communication in general, to know that words don’t perfectly communicate meaning; they’re just a less unreliable method for attempting to do so. The more words, and the more meaning is communicated, the clearer the communication.

So name your functions and classes well, write your comments, and generate your docs. All of these have an appropriate use and all are necessary.