Organise Your Code
The first time I saw contents in a CSS file was when I decided to view the source of Eliot J Stocks personal website (as you do if you're a web developer) and saw the neatly aligned, borderline ASCII art contents section at the top of his file and thought — ‘ what a loser ’. Now I wouldn’t even think about writing a style sheet without a contents section.
Not only does it make your code look more presentable, it also makes it easier to organise, (especially if you write oocss). You’ll be able to find certain classes a lot quicker, and if you need to remove a section from your site like the navigation, you’re less likely to have an unused CSS.
If you use a preprocessor like sass or less (and now roole), adding a contents section makes even more sense since you can easily locate all your variables, mixins, and media queries. Of course if the code for gets too much for one section you could always put it in a new file and import it to the main one. A contents section only really makes sense if you have multiple sections in one file.
If you’re familiar with smaccs you’re probably writing media queries for different objects of your site instead of putting all the media queries for a break point into one desperate file. Having a contents also helps with this as you can immediately see what objects have media queries, the break points they have it for, and the objects that don’t.
/*
Contents
================================
1. Navigation
2. Hero Section
3. Flavours
a. Features
b. Install
4. Footer
5. Shared Styles
a. extends
b. fonts
================================
*/In conclusion, having a contents section for your CSS (and even JavaScript) files is helpful in a lot of ways. You might not find it incredibly useful at first, but after a few attempts it’ll make a lot of sense.
Written by Richard Bray
Related protips
8 Responses
Hey just letting you know, this post inspired a little rant from me.
@projectcleverweb Wow thanks, glad I could inspire you. Also a very good article, more detailed than mine.
I'd suggest splitting up large files into smaller files containing only related code - if you need a contents section your file is too big.
@faceleg Good point. However if you're writing pure css, more files means more http requests which will slow the load times of the site. Writing in a css preprocessor will rectify this issue of multiple files and works well, but a contents section helps you to find files quickly, (especially if you haven't looked at the css in months), and will help other people looking at your code find the styles they need.
Use a CSS preprocessor (Sass), split your code into different files - that's more organized.
I agree. Use a preprocessor to organise files into smaller chunks during development. A contents may look nice but doesn't prevent large (excessive scrolling) in a CSS heavy project.
Agreed about organization of your source code but you should never see that in production. Good that you discovered this technique... Bad that you saw it as an acceptable way to deliver code.
Good point you raise. I personally don't see a reason why it can't be used in production. Yes if you want to make the file size as small as possible then it makes sense to remove unnecessary comments. However if you use a CSS preprocessor like SASS, and comment out like so '//this is commented out', then the compiler will completely ignore this and produced compressed, comment-less css.
