CSS Organization Methods and Writing Style

Posted: September 01, 2008 Comments(16)

It’s only natural to have preferences. Personal preferences help define your character, your style. Each day, you apply your personal preferences to nearly everything you do, right down to the way you write your code. Some developers don’t even know they’re doing it, while others are outright forceful when it comes to a conversation about whitespace.

I’d like to cover some common techniques for writing CSS. This article is in no way meant to indicate that method A is in any way, shape, or form superior to method B. Please keep that in mind as you read. Topics such as this tend to spark quite the debate, but that’s not my goal. The purpose of this article is to provide insight to other ways of doing things.

Commenting your CSS

As with all software development, commenting is applicable and important when it comes to CSS. Also similar to other software development, with CSS there are good methods of commenting, as well as less than ideal methods. Comments can be useful not only as a personal reference, but also invaluable to your teammates or coworkers.

At the top of the list comes headings/grouping. Many developers will segment their CSS into related groups of selectors. This helps a great deal when it comes to maintenance. Having all of your related styles in proximity with one another is greatly beneficial. There are a number of ways to effectively group your styles by section. My preferred method is as follows:

/* Heading
------------------------------------------------------- */

.selector { property:value; }
.selector #selector { property:value; property:value; }

Creating headings allows me to quickly scan a style sheet and make the change I’m looking to implement. There are many different methods to effectively format your headings, make sure you’re using one that’s easily identifiable, e.g.:

/* =========== */
/* = Heading = */
/* =========== */

.selector { property:value; }
.selector #selector { property:value; property:value; }


/* =========================================
   HEADING */

.selector { property:value; }
.selector #selector { property:value; property:value; }


/* ============== [ HEADING ] ============== */

.selector { property:value; }
.selector #selector { property:value; property:value; }

There are plenty of ways to segment your code with a few simple headings. My only suggestion is that you implement it in some way, and remain consistent with it.

Another fantastic, quick to implement, handy comment is a color glossary. Simply making a quick note at the top of your style sheet can save you quite a bit of time searching for consistent color values.

Leaving yourself (and your teammates) notes via comments, while not very common from what I’ve seen, could prove to be useful. The issue here, however, comes down to why you’re leaving the comment in the first place. If your styles have become so convoluted that you’re leaving an explanatory note, you may want to revisit the cause of the requirement.

Single Line vs. Multi Line

As you may have noticed in my samples, I write single line CSS. Single line vs. multi line CSS has been a debate since the beginning, and continues to evoke heated discussions to this day.

Most of the debate stems from a direct disruption to the overall readability of the style sheet. Many developers see single line CSS as completely unreadable, while others feel the same way about multi line. I think the main reason behind that is because each developer is looking for something different when they read a style sheet. I, being of the single line variation, hunt for selectors first. Once I’ve found my selector, I’ll continue to look for my desired property/value combination, and go from there. Multi line developers seem to hate the fact that property/value combinations aren’t given nearly as much ‘weight’ as selectors, greatly reducing readability.

Both camps are right. There are pros and cons to each way of writing CSS, and at the end of the day, like with all things, you need to do what’s best for you. Just because someone else uses slightly different formatting doesn’t make them any better or worse.

Proposed solution

I write my (single line) CSS in CSSEdit. One of the reasons I like to use the application is because it’s got reformatting built in. If I need to work on a multi line style sheet, CSSEdit will reformat it to my liking with the click of a button. When I’m done, I can reformat it back to the way I found it and call it a day.

Unfortunately, CSSEdit is a Mac application, and there are quite a few developers who don’t run OS X. To ‘share the wealth’ of this feature in CSSEdit, I took some time to put together a CSS Reformatter. Powered by the sweet CSSTidy, the Reformatter lets you paste your CSS, choose a template format, and provides a reformatted style sheet for you to work with.

I haven’t had a whole lot of time to work with it, but the Reformatter also allows you to implement your own custom CSSTidy templates. If you don’t like ‘my’ multi line or single line templates, feel free to use your own.

Again, it’s not a matter of one method being superior to the other, just be sure to use what you’re comfortable with. Establish a standard among your team, and reformat your CSS to that standard before stopping work on it. Everyone = happy.

Other methods of organization

One technique that has come up from time to time is that of alphabetizing your CSS. Basically, the idea is to alphabetize both your selectors as well as properties to make finding specific declarations a very speedy process. At first I was a bit taken back by this approach. It seemed like quite a bit of work both in the initial writing as well as maintenance of a style sheet. I suppose, however, if you’re accustomed to writing CSS this way, you’d be very quick in locating various items in your style sheet. Unfortunately, I don’t like this technique simply because it removes all structure from your document. You could say it’s structured based on the alphabet, but in my opinion segmenting the styles based on their context is a bit more applicable.

In mentioning ‘findability,’ I’d like to also bring up flagging. Many developers will use certain special characters in their comments to allow quick scanning of a style sheet by way of the editors built in find functionality. For example, you can flag certain comments with an equal sign to signify it is of one ‘group’ of selectors, your heading for instance:

/* =Heading
------------------------------------------------------- */

.selector { property:value; }
.selector #selector { property:value; property:value; }

The idea behind such flags is to bring up the editor find dialog, enter ‘=’ and simply search your sections one by one. Personally I haven’t adopted this approach in favor of straightforward heading comments, but I can definitely see value in it. An issue that may come up, however, is standardization of the flags amongst your team. Make sure everyone is using the same flags for the same purpose, else you’ll be both confused and frustrated when picking up where someone else left off.

Separating style sheets

A technique I’ll see from time to time, is that of separating style sheets into different files based on purpose. That is to say, there will be one style sheet for typography, another for colors, one for layout, and more. The purpose is to abstract certain selectors based on what you’re looking to do with them, as well as trim the overall length of your document.

Personally, this method has been more cumbersome than useful for me. I find it difficult to force myself to take care of all the type in one style sheet, colors in another, etc. Additionally, when it comes to maintenance, I dislike the fact that I potentially have to open multiple style sheets to make a ‘single’ edit.

Style sheet compression

The last bit I’d like to touch on is CSS compression. To be brutally honest, I never compress my CSS before deployment. I think that may be because of the way I write CSS, however. Since I write single line, compression rarely yields anything more than marginal reduction. I’d rather save myself the extra layer of maintenance in remembering to keep an uncompressed version.

There are times, however, when I think compression can be a very useful thing. It’s important to keep in mind that Web browsers download style sheets in their entirety. Anything you can do to reduce that latency will improve performance. If your writing style produces quite a bit of whitespace and/or comments, it may be in your best interest to compress your CSS before deployment.

My style

As I mentioned, every developer writes their CSS in a unique way (more-or-less). I write my CSS on a single line basis in CSSEdit. I don’t use CSSEdit for the Preview functionality or anything like that (although it is quite nice), I use it for two reasons. Number one I mentioned earlier; it has built in functionality to reformat CSS on the fly. The other reason I use CSSEdit is because the application allows me to generate a tree structure within my document by way of flagging comments:

Screenshot of CSSEdit

The left column in the interface is a folder structure which allows me to interact with the sections of my CSS. I’ve come to rely quite a bit on this little feature, and it’s one of the main reasons I don’t use my regular text editor when working with CSS.

I hope this piece was at least in part interesting to read. I’m always curious to find out how other developers get things done, so if you don’t mind, take a minute to leave some feedback based on your preferences. The more you’re exposed to as far as methodology is concerned, the better equipped you are to evaluate the way you do things.

Get my newsletter

Receive periodic updates right in the mail!

  • This field is for validation purposes and should be left unchanged.

Comments

  1. Nice article!

    I like to write my CSS codes in single lines. It’s easier to find what I want and remove file’s weight, an important thing to do faster websites.

    Whatever, I use Coda to write HTML and CSS, an editor that I’ve discovered and liked too much. Give it a chance 😉

  2. I feel bad for re-igniting the CSS formatting debate via this tweet, but what it really boils down to is ease of maintenance for the person or team working in the code. Personally, I prefer multi-line with indentation, because that’s how I write in any other language. But, to each his (or her) own, whatever works.

  3. I wrote my own guide to CSS formatting over two years ago, and it’s largely stayed the same ever since. You may find it interesting, you may not:

    http://mattwilcox.net/archive/entry/id/642/

    I use a hybrid line layout, split on all properties leads to far too lon a file, and single line leads to horizontal scrolling – I don’t like either of those problems 🙂

  4. Leaving yourself (and your teammates) notes via comments, while not very common from what I’ve seen, could prove to be useful.

    The reason why I sometimes find myself doing this is to explain something that might seem weird. For example, an extra margin that needed to be put in for a particular browser. It can be frustrating to try to figure out even your own work years down the road, let alone CSS written by someone else. I don’t comment too often but if I think I might forget why I did something I’ll leave a little note.

    I’ve been experimenting a bit with separating as well. It can be cumbersome but, then again, so can working with one really huge CSS file! Separating based on purpose (layout vs. content or layout vs. style) seems to be working well for me. I’m not too strict about it though.

    I like the looks of CSSEdit. Too bad I’m not on Mac anymore! Autocompletion is absolutely essential for me. On Linux I like Quanta Plus.

  5. @Carlos Eduardo: I love Coda. It’s a beautiful thing. However, I’m fully addicted to snippets in TextMate, so it’s a bit of a deal breaker at this point. As soon as Coda has a built in snippet engine, though, I can bet that I’ll be switching.

    @Nathan Smith: You’re spot on; it does indeed come down to maintenance. With the tools available, we can easily reformat CSS to work with, then revert to the old style before putting it back. Don’t feel bad about sparking a debate! We all love it when that happens, no matter what anyone says. Debates are healthy (most of the time).

    @Matt Wilcox: That’s great. It’s awesome to read how other designers think when they’re doing what they do.

    @Ole: Thanks for the insight on your style!

    @Megan: Great explanation, it makes perfect sense that you leave a note or two in your CSS. Sometimes we all need to leave ourselves notes just to trigger the thought process we were in at the time. CSSEdit is nice, however it’s a bit cumbersome to use one app to edit code and another to edit styles. I’m in the habit now, though, so it’s not too bad. I was using Quanta Plus during my Linux phase, that’s a great app!

  6. Ditto on headings and comments.

    One thing I didn’t see addressed was the order of rules. I always do display properties first, margins, padding, borders and background next, text and font properties last.

    Single rule styles go on one line, everything else is expanded. If there”s multiple selectors for one style block, they are return separated (clearer and the same number of bytes as a space.)

    That’s my personal preference, but as you state, the important thing is to pick a pattern and stick to it.

    With servers being able to send gzip (and if your server isn’t, why not?) I really don’t understand the fetish with trying to save a few bytes by trimming whitespace (or crazy things like removing the last semicolon.)

    That said…

    I’m a BBEdit fan and have two perl filters that I use in BBedit to compact/expand styles. I mainly use these to reformat things I encounter from other authors and/or to fit in with the “local” style of the project. Fold, spindle, mutilate, steal to your heart’s content:

    http://pangram.org/misc/css-compact.html

    http://pangram.org/misc/css-expand.html

  7. I wouldn’t recommend splitting CSS into several files, your site will take longer to load since you have all the extra HTTP requests, even if the files aren’t really all that “heavy”. Sure cache helps but that’s up to the visitor.

  8. Multi-line all the way, and I often don’t even shorten properties like background. I do shorten margin and padding though. I like the CSS as readable and scannable as possible.

    I group by base styles (reset, html and body), ‘top-level’ selectors (h1-6, p, ol, dl, links etc.) and then by document section (header, content, ancillary. footer etc. – this section will contain classes and ids) Separating by media works really well, I find, as you don’t have to think about different types of media at the same time.

    I’ve started to use a table of contents, although it’s too early to say how useful that will prove. It takes quite a long time to implement.

    I guess all this adds to the file size, but there are other ways to reduce the overall document size.

  9. Jonathan, thanks for this post!

    I use CSS Edit, and I did not know about the Groups feature. This is really nice. I found the side panel that shows the selectors to be annoying, and wanted it to go away. However, now that I have grouped all my selectors into folders, it is very nice.

    I will stick with the multi-line, because I’ve always been a very white-space friendly coder. But also, because I’m using a standard-size MacBook Pro, so I want to keep my CSS window narrow.

Leave a Reply

Your email address will not be published. Required fields are marked *