How should you comment CSS?

I think there are generally two cases where comments should be used:

  1. If you are using hacks.
  2. To illustrate the page structure.

This may be beyond the question, but you should first ask: how to structure CSS?

With a proper structure, comments make it a breeze to navigate and locate the sections in your page, e.g.

/***************
 * UI Elements *
 ***************/
h1, h2, h3, p {
    ...
}
table, form, input, textarea {
    ...
}

/* Custom Radio button hack: use background-image/position on label */
input[type=radio] {
    display:none; 
}
input[type=radio] + label {
    background-image: url(...);
}
input[type=radio]:checked + label {
    background-image: url(...);
}


/**********
 * Header *
 **********/
#site-header {
    ...
}
#logo {
    ...
}

/***********
 * Sidebar *
 ***********/
#site-sidebar {
    ...
}
.item-in-sidebar {
    ...
}

/**********
 * Footer *
 **********/
#site-footer {
    ...
}

Anyone touching the CSS should have the confidence that editing something in, say, the header section won't affect anything else on the page. If a fundamental change in an element's style is required across all pages and sections, all you need to do is edit the relevant element in the UI Elements portion of CSS.

Needless to say, good CSS structure depends on your markup being well-written and cleanly separated from presentation. If your HTML is afflicted with div-itis, no amount of comments can help save your CSS.


It's not a standard to add comments to CSS, but if you want you can do so. Here is an example of how Daniel Eden, who created animate.css, added a comment in the header of his CSS file:

/*!
Animate.css - http://daneden.me/animate
Licensed under the MIT license - http://opensource.org/licenses/MIT

Copyright (c) 2015 Daniel Eden
*/