Better CSS

Lesson 3: Naming

Nam­ing things is hard, so hard in fact that you’d be hard-pressed to avoid the fol­low­ing quote (it’s become a bit of a meme):

There are only two hard things in Com­puter Sci­ence: cache inval­id­a­tion and nam­ing things — Phil Karlton

When we talk about​“names” in CSS, what we’re really tak­ing about are the dif­fer­ent attrib­utes we give to HTML ele­ments to identi­fy them. Things like class names, IDs and name attributes.

Use Semant­ic nam­ing #

Semant­ic nam­ing is a com­monly prac­ticed philo­sophy in CSS, it’s main ten­et is:

Explain what an ele­ment is, not what it looks like

Ima­gine describ­ing an ele­ment on a page to someone who isn’t able to see it. Instead of rely­ing on it’s visu­al char­ac­ter­ist­ics (“it’s the big red but­ton”), you’d have to con­sider some of the following:

Example #

Let’s con­sider an example. We have a bunch of text and want to make spe­cif­ic words bold.

See the Pen  Les­son 3: CSS name coup­ling 1 by Joe For­shaw (@joeforshaw) on Code­Pen.

Seems sens­ible enough so far. A few weeks later, we decide that instead of mak­ing these words bold, we want to make them pink!

See the Pen  Les­son 3: CSS name coup­ling 2 by Joe For­shaw (@joeforshaw) on Code­Pen.

But we’ve for­got­ten to update the class name to reflect the changes to the CSS, so now there’s a con­fus­ing semant­ic mis­match. We’ve got a class that says that the text is bold, but in real­ity it’s pink and not bold! Any­one new com­ing to this HTML is going to have a puzz­ling job of fig­ur­ing out what’s going on.

To rec­ti­fy this situ­ation, we need to update all the class names to some­thing that accur­ately reflects the cur­rent nature of the pink ele­ments. We could rename the class to .pink-text, but this just leaves us in the same situ­ation as before! If we decide pink isn’t the col­our for us, then we’ve got to go and rename all the classes again.

In this toy example, it’s not a big deal and would only take us a few seconds, but in a large code­base these classes could live in Javas­cript, HTML and/​or CSS in all sorts of inter­pol­ated and con­cat­en­ated formats. Find­ing every occur­rence can be quite tricky and has a high chance of silently break­ing some part of the visu­al design if you miss anything.

So what’s the solu­tion? Semant­ic naming!

But before we arrive at the fix, we have to prop­erly under­stand the prob­lem. The core issue is that we’ve named the class by it’s visu­al prop­er­ties which, in an evolving front-end, will often change. To find a solu­tion, first we have to fig­ure out why we are mak­ing this text bold or pink. What’s the inten­tion? What’s the point?

In this scen­ario, what we really want to do is high­light or emphas­ise these spe­cif­ic words to the read­er. We want to visu­ally accen­tu­ate that these words are important.

So now we under­stand the prob­lem, what do we name the class? Well just by stat­ing our inten­tion we’ve armed ourselves with the vocab­u­lary! High­light, emphas­is, accen­tu­ation. Any of these would work a treat, and the best thing about them is that they accur­ately describe the ele­ments without coup­ling them­selves to spe­cif­ic visu­al design decisions.

So to summarise:

Avoid coup­ling names to CSS rules

Train your nose to these kinds of code smells, .red-button, .margin-bottom-20px, .left-aligned-text. 💩🤢

Semant­ic names are more main­tain­able #

As the above example illus­trates, semant­ic nam­ing is more resi­li­ent to design changes; classes are more likely to be rel­ev­ant to the ele­ments they’re applied to and less likely to become out-of-date.

It also has the advant­age of doc­u­ment­ing your ele­ments. If you’re annot­at­ing, via class names, what each bit of HTML is instead of how it looks, then someone unfa­mil­i­ar with a bit of UI can see how the HTML and CSS join up to the visu­al elements.

That means bet­ter know­ledge-shar­ing and less men­tal load when work­ing with semantic­ally-named ele­ments, pro­du­cing a more main­tain­able code­base overall.

Try to avoid name col­li­sions #

In CSS, name col­li­sions com­monly refer to when you acci­dent­ally give an ele­ment a name that is already used by an unre­lated, exist­ing ele­ment. When this hap­pens, the styles you give your new ele­ment will start to inter­fere with the exist­ing elements.

These issues are sneaky and hard to spot, as the ele­ments you’re impact­ing may be in a totally dif­fer­ent sec­tion of your site. You may not think to check the con­tact page if you’re edit­ing the home page! This over­ride beha­viour is core to CSS’s cas­cade, but unfor­tu­nately assumes authors are omni­scient and don’t make mistakes!

Let’s dig into some solu­tions to tackle name collisions.

Short­er names ➡ more reusable #

Try to adhere to the fol­low­ing nam­ing convention:

Keep an element’s name length inversely pro­por­tion­al to it’s reusability 

In oth­er words, use short­er names for widely-used, reusable ele­ments and longer names for uncom­mon ele­ments that are used maybe once or twice.