Create Maintainable Code with a CSS Styleguide

Back when I was in school a teacher instilled in me a strict eye for code style. We submitted our assignments electronically to a testing script on his account, but before an assignment began running the rigorous gamut of test cases, it had to first pass a style check.

The style check was quite a trial in and of itself. It usually took several iterations of submissions just to get the code’s style in order. On top of that, a submission could only be made once in six hours, and a failed style check gave no specific errors. Pass or fail. This prevented us from simply guess-and-checking our way over this hurdle and made us really look at our code.

Every student came out of that class with pristine code “handwriting.” To this day, if I see a pile of sloppy code, my fingers land squarely on the tab and arrow keys. It is amazing how much easier consistently and clearly formatted code is on the eyes.

The advantage to clean code style is readability. The structure of nested and correctly tabbed HTML elements is visually apparent. Variable capitalization strategies help segregate variable types on the page. Standard code organization lets you know exactly where the code is that you are looking for.

The specifics of the rules used in a style guide are not as important as consistency. If you follow a style rule everywhere, the rule can be figured out. If you are not consistent with your rule, there is no rule. It is best to come up with a set of in-house rules everyone follows and can get used to. Write them down and them stick to them.

Variable Names

• Variables should be camelcase, with a lowercase first letter — examples: articleDate, userDetails, spoon
• The name should refect the semantics of the element, rather than the style — examples: tinyFont (bad), imageCaption (good)

CSS Rules

• Selectors ( form input { … )
  • One selector per line
  • The opening brace resides on the end of the last selector’s line
  • Use of element tag name with class
    • Only specify the element name if done for semantic reasons. You are effectively saying you want the rule only applied to elements of a certain type. Otherwise you are needlessly restricting the markup.
  • Style link pseudo classes in this order: link, visited, hover, active. Some browsers get mad it you do otherwise.
• Attributes ( … font-size: 12px; …)
  • Each attribute has its own line
  • Each attribute line is indented one level (use a tab not spaces)
  • The closing brace resides on its own new line after all the attributes
  • Attributes should be sorted in a standard order
    • positioning, sizes
    • margins, padding, borders
    • text
    • the rest
  • Use short-hand notation whenever possible
    • margin/padding/border-width: top right bottom left
    • border: style width color
    • font: style size family
    • don’t use short-hand when you only mean to affect one attribute (e.g.: margin: 0 0 5px 0; is bad)
  • Don’t use quotes for filenames
    • eg: background-image: ("/images/dude.jpg"); (bad)
    • It’s unnecessary
    • It makes IE on OSX mad (although I’m not really friends with IE on OSX)

Organization

As CSS files get larger it is important to have a standard high-level structure in place. This guides users where to put new rules and allows them to become accustomed to finding a particular type of rule they are looking for. Here is my proposed structure.

• reset
  • Use a variation (if not exact) of Eric Meyer’s CSS Reset
• site defaults
  • This is where you redefine all the basic tags for your site. You’ll handle the body, links, headers and such here.
• generic styles
  • This is where you create generic utility classes that you can use as a “toolkit” within your site. For example, clearing elements or generic form input styles. In the past, I’ve create table.dataList to use for debugging purposes.
• shell
  • This is where the layout is styled for the shell of the site. The shell is the outer layer of the site that exists on every page. The shell will have the site container, the header and the footer. Frequently, an important job of the shell is to set the width of the website.
• layout
  • Your website will probably break down into several templates. This is where you style the wireframes for those templates layouts. This section usually has a lot to do with columns.
• modulars
  • You may have small portions of your website that are styled the same, but across many pages and in many locations. Here you can make those modular boxes for reuse.
• section/page specific
  • Once you’ve got everything else covered, you’re only left to style elements individually. This may mean stying a box that appears in several pages in a section or a unique element on the site.
• subsections
  • once your sections get large enough, be sure to divide them into logical subsections

Comments

I’ve got two uses for comments. One use helps with organization. The other is to explain an unusual or complicated use of css. Remember, comments start with /* and end with */. You cannot comment out a line to its ending using //.

Obviously, one would use comments to create section dividers. I don’t have a strict rule for format because my dividers tend to grow in size proportionately with the file. When I start a file, I will estimate it’s final size when I create the first comment, but I might update the style as I go along.

Initially, my section dividers look something like this:

/* Header --------------*/

but could grow to as big as

/*####################################
#  Header                            #
#####################################*/

As I get larger dividers (and each section gets more rules), I’ll add sub-dividers. Usually these are in the style of the previously used header. Regardless, I make the dividers nice and long so they stick out farther than attributes. This makes spotting them easy when furiously scrolling. As my dividers grow bigger I begin to use more “bold” filler characters. In this case I moved from dashes to pound signs.

The other comment use is for explanation. If the comment is about a single attribute, put the comment on the end of the attribute’s line. If it is about a rule, put it on the line(s) about the rule. If it is about a section, put it below the section comment with an empty line after it (to show that the comment is not referring to the first rule). If the section comment is big enough, go ahead and put the explanation in there.

Future Topics and Conclusions

In the future I will get into CSS best practices with functional implications.

For now, I hope this helps you (or those programming with you) towards clean CSS code style. As I mentioned before, this is not the right answer, but an answer. It doesn’t matter what you do as long as you do something and stick to it. In fact, being adaptive is a skill. Getting good at good style is better than getting good at a specific good style.

My point there is that you will never convince the whole world to code your way, so you’ll always run into different styles. Being good and picking up and continuing encountered styles will prevent “dual-style.” I can’t decide which is worse: no-style, or dual-style.

Anyway, the worst case scenario is a haphazardly authored file. No one wants to look at that.