This is where Adam Spooner writes.

Thoughts on Writing Team-Centric CSS

Posted on

I’ve worked on a few different front-end development teams over the past few years, and I’ve seen a range of coding practices—the good, the bad, and the ugly. What follows is a compendium on CSS organization.

Follow Your Code Standards Guide

I want to be clear, before I dive into any specifics, that you should always follow the code standards or style guide for the team you’re working with. The goal in code organization for a team of any size is clarity and consistency. Your code base should look as though one person wrote it. If you don’t have a code standards guide, then I implore you to write one or adhere to someone else’s.

Use Ample White Space

White space is a key component for clarity in any aspect of design, whether it’s visual design, writing, coding, etc. White space is free, so you have no reason to be stingy. I recommend using a single line break between properties in a property list; two or more line breaks between declarations starting with the same element, id, or class; and four or more line breaks between declarations for different elements, ids, or classes. One exception is a declaration with one property-value pair; the declaration and property-value pair can inhabit the same line. There’s a nice side effect when using this style for line breaks: understandable and easily-skimmed git blame (or whichever repository flavor you use), diff, etc.

Comment Liberally

Most developers I work with shy away from comments, but I find them indispensable. Annotating your code allows others on your team to understand why you’ve chosen a certain technique. Alternatively, you could just ask why your teammate chose a certain method. This approach is fine for small teams, but it’s nearly impossible for large teams. Answering the same question multiple times is a waste of time.

A well-written annotation also helps you. Sometimes you need a reminder for why you wrote a declaration a particular way. I know comments have saved me from myself more than once. Good documentation saves time.

Comments also add clarity. As Donald Knuth said, “I still think people could be documenting what they write much better. And a comment is different than writing an essay. The way you write a program for another human being is completely different from the way you write it for a computer.” Your teammates are not computers. Write a commentary they can understand. Remember, the goal is clarity.

What About File Size?

I often hear this argument, “Well-documented code with ample white space sounds nice in the theoretical world, but it leads to larger file sizes in the real world. And serving large files is not good.” I’ll be the first to say serving large, fully-commented, abundantly white-spaced files is bad. This sounds like a contradiction to my advice on writing team-centric CSS, but it’s not. The files your team uses and tests with should be different from the files you serve your end users. How is this possible? Minification and compression. A major component in any team’s build process should be the step where comments and white space are stripped from the production files. I use YUI’s Compressor and gzip to drastically reduce file sizes for lightweight production files.

This leads to another valid argument, “Multiple versions of the same file bloat the repository.” I agree. They do. My only counter is that having well-documented, amply white-spaced code adds clarity and consistency in a team environment. The trade-off is well worth it.

Maybe you’re a freelancer and have worked on a few different teams. Maybe you’re a one-man shop. Maybe you’re part of an in-house team. Whatever your role, I hope you found this advice helpful. I don’t claim to have the ultimate answers for code organization, and I’d love to hear how you organize your code. and share your wisdom.