Tips for Improving Your CSS Code Comments

Wednesday, December 19, 2012

Building a CSS stylesheet is not often the most difficult task when constructing a website. However putting together readable styles which still make sense months down the road may be a challenge. Web developers often get lazy and struggle to keep their documents organized.

Thankfully there are some easy steps you can take to build your stylesheets with a very clean codebase. In this article I would like to introduce some ideas for writing clean CSS comments in your code. Commenting is a useful practice not just when coming back to your own files in the future, but also for other developers who are picking up your work. Play around with just a couple of these techniques and you will certainly notice a difference in the readability of your stylesheets.

Basic Organization Techniques

I like to usually split up my CSS documents by using comment blocks as headers. I place these between large segments of style selectors which each pertain to a different area on the page. For example, I usually start with browser resets and eventually move into typography and page containers.

You may split these up into any style which is easiest for you to read. If there are thousands of lines in your document it may be worthwhile to setup a small table of contents right at the top of your CSS file. Then using a unique numbering key(such as 1.001, 1.002, 1.003) you can do a search in the document to quickly jump down to any area.

This organization technique is great for readers as well as developers. You may find web designers who want to look through your work and struggle to find a particular set of styles. By placing headers throughout your document it becomes a lot easier for other designers to quickly skim your work – even without editing the file at all.

Handling Browser Quirks

The majority of browser quirks you will run into generally involve Microsoft Internet Explorer. Now this isn’t to say you won’t experience rendering issues within older versions of Firefox or Safari. But Internet Explorer 6, 7, and 8 all follow their own general rules for rendering websites.

This will sometimes cause issues in your layouts and fail when using new CSS3 properties. It is true that much fewer people are using these older legacy browsers in modern day. But it is also true that you cannot discount the folks who are! I recently found an excellent article which outlines common IE bugs in CSS and how to fix them quickly.

Splitting Aesthetics from Positioning

In some rare situations I have seen web developers splitting individual properties by using CSS comments. You may consider how the main stylesheet functionality includes both positioning and colors/styles. Check out the small code example below:


.container {
  /* positioning */
  display: block;
  left: -9px; /* needed to fix container margin */
  padding: 12px 7px;
  margin-bottom: 10px;

  /* aesthetics */
  background: grey;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4x;
  border-radius: 4px;
}

Now this isn’t a technique you would need in every situation. But for some element selectors you may end up with 15-20+ different properties. Unless you organize alphabetically or by text length, you can expect these selectors to grow very complicated and messy. But thankfully breaking down your styles into a block-line syntax also improves readability.

Setup Readable Comments

There are situations where placing comment blocks next to your properties are just too much. Consider how you write your CSS styles for each selector, and where they should be placed in the document. If you are using block-line CSS code as I have written above then you may consider placing comments right inline.

But there are going to be situations where it feels better to create a whole block of comment code. This is the perfect syntax if you want to explain why you are writing a certain piece of code. Whenever I place code blocks with comments using multiple lines I separate the new lines with asterisk’s on the side. Let me demonstrate another brief example.


/**
 * setup for page wrapper container.
 * inner wrapper holds the page content,
 * while outer wrapper centers at max 900px width.
 */
#container { }
#wrapper { }

This is actually very common practice among PHP and Ruby developers when setting up function descriptions. I feel these are much easier to read than one long line of comment text, which appears to just blend in with the rest of our styles. But the most interesting part to writing CSS comments is how you can mix & match syntax styles. Toy around with your own ideas and you may be surprised at how quickly you adapt to writing unique yet helpful code comments.

Final Thoughts

CSS web development is all about organization, metrics, and layout styles. Often times you will run into bug fixes or have to setup outlandish properties for handling browser quirks. But this is all merely part of the web development process.

I would argue that code comments are not always necessary, but definitely produce a solid level of trust. Other developers who find your code will have a much easier time reading through documents. It is my hope this article will provide a few tips for developers to grow accustomed using CSS comments. If you have similar ideas or questions feel free to share with us in the post discussion area below.