CSS comments: how to use them

This post focuses on the use of CSS comments for organizing style sheets. I'll review the most popular practices used so far by web developers, adding some hints based on my personal experience.

Comment syntax

The syntax of CSS comments resembles that used by many high-level programming languages, such as C++, Java or C#. In CSS, comment blocks start with a slash followed by an asterisk and end with an asterisk followed by a slash. This structure is used either in single-line comments or in multiple-lines ones. Here's an example:

/* A single-line comment */

/* Another comment */

/* This comment spans
   multiple
   lines */

CSS comments are ignored by the CSS parser and you can put them everywhere in a style sheet, even inside a rule or declaration. Note that everything appears within a comment is ignored as well, including CSS rules or declarations. We'll see how to take advantage of this aspect in the next section.

Debugging CSS with comments

CSS is not a programming language, so it has no notion of break points (very useful in debugging). However, we can use comments to keep track of our trial-and-error efforts when we have to modify declarations or rules, as shown below:

#articles {
  width: 20%;
  float: right;
}

#articles .latest {
  /* width: 100%; */
  border: 1px solid #ccc;
}

The second rule (line 6) shows a potential rendering problem, because the elements with class .latest have yet a stated dimension that equals the overall width of their container. In this case, the children elements will overflow their parent if they have a larger dimension and this floated box will be pushed down. If we want to keep the one-pixel border, we should remove the declaration at line 6. What if our choice is wrong? We can use comments as a fallback mechanism without deleting and rewriting our code. If our choice is correct, we can remove the comment together with the buggy declaration and move on.

Notes and information

Another use of comments, perhaps obvious, is to write down contextual notes for yourself or your development team. Example:

body {
  font-size: 76%; /* Font-size set to 12px */
}

In that vein, comments can also be used to insert information about a CSS file. Such information are generally put at the very beginning of a style sheet, as the following example shows:

/* File: style.css
   Path: www.css-zibaldone.com/style/style.css
   Author: Gabriele Romanato */

In some of my projects, I've also tried another approach by using JSDoc for commenting CSS. Example:

/* @fileoverview style.css
   @link www.css-zibaldone.com/style/style.css
   @author Gabriele Romanato */

However, not all the features of JSDoc can be applied to CSS, although I think this approach is very interesting.

Grouping rules

Basically, a style sheet is made up by a set of rules. When dealing with big files, it's important to create smaller subsets of rules that share some similarities (e.g., they stylize the same section of a document). Comments can be used in this way to keep our files organized. Example:

/* GENERAL STYLES */
...
/* GLOBAL CONTAINER */
...
/* CONTENT */
...
  /* Main content */
  ...
  /* Secondary content */

As you can see, I follow certain conventions when grouping rules with commments. More specifically, I:

1. write a supersection in uppercase letters;
2. write a subsection in lowercase letters and indent it to emphasize the fact that the current section is actually contained withing the preceding supersection.

By doing so, it's easier to grasp the overall structure of the document we're working with.

Comment flags: an improvement

In 2005, Doug Bowman proposed the idea of using a sort of comment flags (i.e., a string of characters) in order to help web developers searching within a style sheet for a specific section or group of rules. His article, that can be found at www.stopdesign.com/log/2005/05/03/css-tip-flags.html, popularized the use of the "=" character as a sort of marker for CSS comments.

Using the search options of your favourite editor, you can easily find all the occurrences of the string "/*=" (or "/*CON") within your CSS file. Simple, smart and amazing, isn't it? The only problem with this solution lies in the fact that it doesn't exist a common nomenclature for the usage of such markers. What if I want to mark up an hack, a bug, a change in the code or a rule used together with some JavaScript library? In that vein, I propose a nomenclature for CSS flags, summarized in the following table.

Table 1. CSS flags nomenclature

Flag	Meaning
=B	Marks a bug (B) or a problem that needs to be solved.
=C	Marks a change (C) or revision in the source.
=F	Marks a fix (F) for a bug.
=H	Marks a CSS hack (H).
=J	Marks a set or rules or declarations that can be used together with JavaScript (J).

Some examples:

#box {
  float: left;
  width: 250px;
  margin-left: 1em;
  display: inline; /*=F Fixes IE's doubled-margin bug */
}

#box h2 {
  font-size: 1.5em; /*=C Changed from 1.4em */
}

#box table tr.even {
  background: #eee; /*=J JavaScript Zebra Tables class */
}

This nomenclature is purely indicative. Feel free to modify it if it doesn't suit your needs.