How should you comment CSS? [closed]

Question

While developing, most of the CSS I interact with does not have comments, besides the occasional header. As a result, I have gotten in the habit of not commenting my CSS.

However, I often find it would be useful to have comments in CSS that I am working with. Should you comment CSS besides a header indicating an author? If so, how?

I am not asking the process of how to comment, but rather the best practice.

Answer 1

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.