Building Style Sheets for Maintainability
On any web project, apart from your own personal weblog, there is always going to be the business issue of maintainability of the CSS (Cascading Style Sheets). For that reason you’re going to have to accept that working in team environments, or even passing over the files to the next developer, are as much what you’re paid to achieve professionally as is the actual up-and-running solution.
Print Your Stylesheet Policy
So how do you write maintainable CSS files? The first step that I would suggest would be to produce a project style guide so everyone who touches the CSS does so with a reasonably similar footprint. I’d go to the lengths of printing that up the old way using flattened dead trees and pass it to everyone who is likely to edit the CSS files the very first day they are given access to that part of your project. The style guide should cover things like your policy on structuring the document and the order you want the authors to enter declarations. For example, if margin and padding are required for any given selector, I tend to put these declarations and follow with floats, widths and fonts. And, if you’re using the cascade to its maximum effect, then that should be in there too. Or you might be coding for redundancy which compromises size for an overall more intuitive and maintainable set of declarations. Similarly, you can state the general formatting rules for spacing and document structure. In fact, the project style guide should have all of this and more.
Include Versioning and Author Details
Right at the top of your CSS file it can help to have just a few lines that are very common on programming files – who is the original author, when was the file made, what version is it, when was it last edited, by whom and for what purpose. This may sound like overkill but for the small hit of having four or five small lines you get the ability to log recent changes with accountability. This may sound trivial but if anyone jumps this step come down on them like a ton of bricks. You may even consider enforcing a hard copy log with a redundant history of this information.
Create a Document Table of Contents
An important maintainability benefit can be achieved by simply dividing each section of the CSS file off into document portions. Give them a small heading and a number as if they were chapters in a book. Towards the top of the file write a standard Table of Contents that states what each section is and provide its section number. This will make life a lot easier for people trying to track down small changes in any given area.
Structure the Document Logically
By this I mean you might choose to divide the CSS file into a portion for colour and fonts with a second portion for layout and structure. Or, and this is entirely a preference decision, you could try to follow the table of contents order of the XHTML content down the page. The idea is to create a document that is predictable and where selectors have a degree of instant findability. This will also save you from inadvertant hack attempts to solve difficult bugs – don’t underestimate how fast ad-hoc changes all over the page can trash your good work and effort.
Provide Semantic Names
The value of having id and class names that make functional sense cannot be understated. People map them much better in their own minds given that they make logical sense. And, realistically, non-semantic naming like “left column” or “red” become confusing when left column gets floated right and red changes to orange or blue. Naming conventions are a critical component of maintainability. And please avoid nonsensical shortcut names like “ho_43″ that might save you a couple of bits in filesize but will even be forgotten by their author by the end of the day! No ho_43’s or related unsemantic gibberish.
Complexity or Redundancy?
As mentioned in your Style Sheets Policy document, you have the choice to either make your CSS short and concise taking advantage of nuances of the cascade. Or, you could code for redundancy so the rules are a lot more obvious. The same applies to using shorthand or longhand approaches. The aim isn’t perfection as much as consistency. You either do things one way or the other – but you do it that way ALL the time!
Comment Your Bug Fixes
Its always appreciated when I access a third party CSS file when the author has documented notes on different browser bug fixes. First, it allows me to learn something new. Second, its got the benefit that I’m not going to wind up pulling apparently superfluous rules out while chasing down unrelated browser bugs. How hard is it to note after a given rule that it fixes layout issues in Opera or Safari? Remember, every time you make changes to the CSS you’re going to have to test. When it comes to bug fixes you’re courting danger by not marking their payload accordingly.
Conditional Comments for Internet Explorer
Avoid hacks at all costs. Eventually that exploit which makes the hack work will be fixed in a given browser and you’ll get a lot of phone calls to go back and fix all those bugs again for free. Write this on your whiteboard – I DON’T HACK. Instead, if you have something that doesn’t work correctly in Internet Explorer version X, and it will most likely be a box model issue involving margin or padding, then use conditional statements to call an extra Internet Explorer only stylesheet from the head section of your HTML files where that one offending rule is over-ridden. Conditional statements are not hacks but instead are supported features designed to allow you to target the beast correctly. Hacks will be fixed oneday – conditional statements will be supported long term. DON’T HACK.
Divide and Conquer Approach
One judgement call to make is how to divide your Style Sheets into separate files. There might be obvious areas of the site where a section of rules (for example a complex home page layout) don’t apply for any other page. For that reason the rules can be peeled off into their own file which cuts the general stylesheet down significantly. Or you could peel off your fonts and colours into one CSS file and your layout and structure into a second. But divide and conquer is a judgement call because you have to weigh up the overhead of downloading several small CSS files instead of one larger one. As long as you understand that each file requires an initial request / response to download but that once downloaded the CSS files are cached.
Minimum Footprints Where Possible
By that I mean you should reduce as much as possible the access to these files. Any time you make a bug fix or make layout changes you need to go and substantially test the site again. Its not enough to see that your list now looks correct – retest every page with a list. It could be very embarrassing for a change to go untested and to find out a week later that a layout issue had gone undetected. Add to that a failure to log the time and reason for changes and in two weeks or even two hours you might not have any idea what broke the layout in section X. In short, provide a single person the rights to edit the files if possible.
There are probably as many more things you could include on this list. We all have evolved different ways of surviving in the mad world of CSS development. The important step is just in starting this momentum towards order. In admitting that there might be a problem. I’ve been a slow learner on CSS maintainability but take it from me – once you use these methodologies you’ll never go back to that ad-hoc black art style. Good luck!
Update: 6 June, 2008
I’d also suggest using a CSS Reset at the beginning of your main stylesheet so that most of the cross browser issues don’t even raise their head. One example is Eric Meyer’s CSS Reset v1.0 but do so with an awareness of the overheads involved. If you’re comfortable only turning off the necessary portions as you build your own style sheets then that’s all the better, too. CSS Reset is just another option – home spun or second hand.
