Be a CSS Team Player: CSS Best Practices for Team-Based Development
Emily P. Lewis | May 5, 2010
How many times have you picked up a project that someone else started, only to discover that the creator's original code is a mess? Or you work with several team members, each of whom has their own way writing code? Or you revisit a project you created years ago, and you don't remember what you were thinking?
It happens to me all the time. In fact, I recently spent almost 300 hours fixing a vendor's facepalm-inducing CSS. Those 300 hours were filled with frustration for not only myself, but other members of my team. And it stole valuable time and resources that would've been better spent on new development.
If that vendor had simply followed some basic guidelines in his CSS, precious time and money would've been saved for my employer, not to mention my own sanity would be in a much better state. In this article, you will learn best practices for writing CSS to help you avoid inconsistency and redundancy; in effect, setting standards that streamline team-based development.
Good organization is the foundation of well-written CSS. It helps me — and whoever has to update the code in the future — understand and scan the CSS and more quickly jump to specific styles.
Before I even start writing styles, I first define the organization of my CSS document according the different content "sections" of the web page I'm styling. More often than not, these sections are the same across different web sites:
So, within my CSS file, I add comments indicating where the styles for each of these sections will go:
Note that the very first organizational comment I added is GLOBAL. This section doesn't correspond to any specific content on my site, but instead serves to indicate where I'll maintain what I refer to as "global" styles. These are generic styles, not specific to any site content, such as those for layout/structure, typographic elements — headings, paragraphs, lists and links —
By keeping these global, generic styles at the top of my CSS file, it helps me take advantage of the cascade. All CSS following these style declarations will properly inherit attributes, and I can more easily override attributes when needed.
More CSS, More Organization
I work with very large web sites that rely on tons of CSS. When dealing with so many lines of styles, I like to add a secondary level of comments within each section. In GLOBAL, for example, I indicate the types of styles I'll maintain:
And you can also see that I added secondary-level comments to NAV, indicating where styles for the primary and secondary navigation will exist.
This might be overkill for your purposes. In fact, for smaller sites with less CSS, I don't typically use the secondary-level comments. But this additional detail on large CSS files has proven very useful for my team.
The format you should use for these organizational comments is ultimately up to you. What you see in the example above is simply me and my team's preferred method. Some people like to have their organizational comments appear on two lines:
Some people use a special character, like an equal sign, as a flag to aid searching within a text editor:
Some people don't use secondary-level comments. And some folks use an entirely different organizational structure that doesn't divide the CSS according to page content, but instead by element types: headers, images, lists, etc. The key is to define your preferred format and be consistent using it.
Want to organize according to content elements? No problem. If you want lowercase comments, go for it. Don't want to indent secondary-level comments? Don't. Don't like hyphens and want to use periods? Go nuts. Just do what makes the most sense for you and your team.
Comment for Communication
We've taken a look at using comments for organization, but you should also use comments for communicating to the other members of your team or even your future self.
What, Who, When
When working as part of a team, it is particularly useful to communicate amongst members what a given CSS file is for, who authored it and when it was last updated. On my team, we add a "summary" comment to the top of our CSS files that provides these details:
The title information is useful when working with multiple stylesheets, such as one for screen, one for print, one for mobile and even those for IE hacks. The author information allows all team members to know who to go to if there are questions about the original CSS, while the updated information lets the team know when the last update occurred and who made it.
As for your summary comment, include only what is useful to your team. If you don't need author information, skip it. If you want a copyright statement, add it. I've even seen summary comments that include address and contact information:
One of the most helpful uses of CSS comments I've encountered is a color key, where the color palette for the web site is defined:
A color key is particularly useful during the development phase, saving you time from sampling colors or looking them up from some style guide. Need to know the hex value for blue links? Scroll to the key, copy and paste.
On my team, we maintain the color key at the top of our CSS documents, just after the summary comment and immediately before all of the style declarations and accompanying organizational comments. We also try to keep the key simple to keep maintenance simple, but it is up to you how complex you want to make it.
The format, too, is your call. You can keep all the color definitions grouped on a single line, as in the example above, or split them out across multiple lines:
Once again, the goal is to find the format that works best for your needs and be consistent once you've defined that format.
Development & Debugging
There are times when I've been in the middle of development and had to hand off my CSS to another team member. And there are times when I'm banging my head against a wall trying to figure out why IE is borking on my CSS, and I just need to walk away. Comments are essential for these situations.
Making a note to yourself or your fellow team members, indicating what a style is and, perhaps, that it isn't complete saves time and headaches:
I typically format these types of comments differently than my other comments in order to make them stand out more. And I make them as long and detailed as needed. Again, use what works for you.
Keep in mind, though, once you are finished with your development/debugging, it is a good idea to get rid of these types of comments. If they are no longer relevant to the work, they are no longer relevant in the CSS. And they just bloat your files.
CSS resets have become pretty popular. They are styles added to the top of CSS files that set HTML elements to a baseline value in order to avoid presentational inconsistencies —
The above example is an excerpt from Eric Meyer's
Reset Reloaded, which I use often. But I tend to edit his reset to not include any markup elements that I don't use, and I recommend you do the same. For example, the sites my team builds almost never use the
So, I remove those element selectors. It makes a negligible difference in page load times or bandwidth, but I feel it helps avoid confusion amongst team members by not referencing markup that isn't used.
I also make edits to the reset styles if I don't want to override browsers' built-in styles, such as how unordered lists are treated. In these cases, I make sure those elements are not included in the style declaration.
I should clarify, though, that CSS resets aren't for everyone. There are plenty of reasons to not use them. I say decide for yourself and, if you do go the reset route, make your reset styles as clean and specific to your site as possible.
Semantic Naming Conventions
One of the most frustrating things about working with someone else's CSS is when the naming conventions for classor id values make no sense whatsoever. Imagine encountering the following:
I have absolutely no idea what .f23means. And even worse, if there are no organizational comments, I don't know what content .f23 is referencing. Is it in the header? The main content? Navigation?
In these situations, particularly with a large site, it is possible to waste ridiculous amounts of time trying to track down where this
As you can see,
But more than just context, semantic naming conventions are useful for saving time. Consider a company who goes through frequent branding changes. If you developed the CSS using presentational rather than semantic
For example, what if you assigned
If you had instead used
With CSS, I tend to agree with the "less is more" school of thought. Just because you can assign a
During my 300 hours of fixing that vendor's shoddy CSS, I found an overabundance of
While the resulting CSS wasn't, itself, too terrible (redundant, but not terrible) it caused confusion. As the designer who inherited the CSS, I saw the
Classitis != Specificity
And that is just a simple example. A more detailed example of class craziness I encountered seems to result from a desire for specificity:
A much cleaner, lighter solution for targeting the
If you don't need a classvalue to target your elements for styling, don't use them. They, too, add weight to your markup and CSS, and they significantly reduce scannability within the CSS.
You should also note that I referenced only the id value as the selector in the last example:
After that last bit, you may be getting the impression that I don't like lots of
These two declarations are identical, except
And then, in my markup, assign both classes to the content for news announcements:
But wait! Didn't I just talk about semantic naming conventions rather than presentational? I sure did. But there are always exceptions to every rule.
Another problem I dealt with in my 300-hour torture session was identical style declarations sprinkled across multiple stylesheets. The only difference between the declarations, was that each was applied to a different selector:
This not only bloated the already-massive CSS files, but made maintenance a nightmare. The solution is to combine those selectors to reference the single style declaration:
Now, if the style needs to be updated, only one declaration needs to be updated, rather than three.
One-Line or Multi-Line?
All of the CSS examples in this article are written using a multi-line format, where each property-value pair appears on its own line. This is a widely-used convention not only within CSS files, but in books and articles about CSS. Most people feel it is more readable, which is why I used it in this article.
However, for the work I do with my team — especially with large CSS files — I write my styles on one line:
Personally, I feel this is more readable. And my team members agree. When dealing with so many lines of CSS, the multi-line approach becomes cumbersome to scan through. Keeping everything on one line seems to make it easier.
For you and your team, focus on consistency. Pick what format is most comfortable for your team, and use it each and every time.
To Alphabetize or Not?
Some people recommend alphabetizing your style properties within each declaration, so that you can more quickly and easily find a property. This isn't something I've been particular about in the past, but after dealing with that vendor's mess of CSS, I can appreciate that some thought applied to organization within style declarations is a good idea.
What I find more useful than alphabetical order, though, is to organize properties according to context. For example, I like to keep all box properties together. Or if I'm using absolute positioning, I keep those values grouped:
Yet again, there is no right or wrong here. Just decide on a property order and be consistent using it.
Make Shorthand Your Friend
Using CSS shorthand has long been heralded as a method for keeping your CSS light and lean. But it also helps tremendously within teams, not only by aiding scannability, but by setting the standard syntax that everyone should follow. This reduces the time team members spend thinking about and writing CSS.
If you are specifying a value of zero, it isn't necessary to specify pixels (or ems or percentages …):
Hexadecimal colors consisting of three pairs of digits can be reduced by removing one digit from each pair:
Box properties like
Also, with box properties, if your top and bottom or left and right property values are the same, you only need to declare two:
Font properties can be combined:
Background properties, too, are great to combine:
Please note: for the last two shorthand examples, font and background properties, the order you declare property values matters. Be sure to reference the W3C specification.
Validate, Validate, Validate
While some folks think it is a good rule–of–thumb to validate your CSS, I think it is an absolute requirement. Validation gives you a chance to make sure your work is ready to share with other members of your team, along with:
I recommend using the W3C CSS Validation Service.
If you and your team have concerns about file size, page loads and bandwidth (who doesn't), then you should consider a compression tool for your CSS. These tools can do everything from shortening your hex color values to removing comments. Here are a few worth considering:
I do not recommend utilizing compression on staging or development files, because while compression reduces file size, it also reduces your and your team's ability to scan and work with the CSS. All the comments are gone. All white space is gone. You no longer have a CSS file that easy to work with. Leave compression as the last step for live/production files.
Tip of the Iceberg
What I've covered in this article is just a handful of basic practices to help keep you and your CSS team happy and working efficiently. There are dozens more guidelines you can follow to further make your CSS the best it can be. If your curiosity is piqued, I recommend you continue reading:
Follow the Golden Rule
Whether you work on an internal team, with vendors and sub-contractors or by yourself as a team of one, these CSS practices will help establish the ground rules for being a good CSS team player, saving both time and frustration.
Just hearken back to your pre-school days and remember the Golden Rule: do unto your CSS as you would have others do unto it.
About the Author
Emily Lewis is a freelance web designer of the standardista variety, which means she gets geeky about things like semantic markup andCSS, usability and accessibility. As part of her ongoing quest to spread the good word about standards, she writes about web design on her blog, A Blog Not Limited, and is the author of Microformats Made Simple and a contributing author for the HTML5 Cookbook. She’s also a guest writer for Web Standards Sherpa, .net magazine and MIX Online.
In addition to loving all things web, Emily is passionate about community building and knowledge sharing. She co-founded and co-manages Webuquerque, the New Mexico Adobe User Group for Web Professionals, and is a co-host of the The ExpressionEngine Podcast. Emily also speaks at conferences and events all over the country, including SXSW, MIX, In Control, Voices That Matter, New Mexico Technology Council, InterLab and the University of New Mexico.
Find Emily on: