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.