CSS Comments – A Good Thing

January 29, 2007

I am beginning to understand just how helpful /* CSS comments */ can be (or would have been!), particularly at work. Taking over support of an 800-page website with mostly-uncommented style sheets is not easy. Types of comments that I plan to add and/or use in the future:

CSS Hack Labels

Briefly describe why a hack was used, which browser it is for, what the hack is called, and a URL where the hack info can be looked up for reference. This will help anyone who needs to edit your work in the future to understand why a hack is there, and if it is still necessary.

#myDiv
{
border: 10px solid;
padding: 10px;
width: 100px !important;
width: 140px;
width/**/:/**/100px;
}

/* #myDiv uses the Box Model Hack so that it will be the same width in IE 5.x as in other browsers. See Technique Two here: http://css-discuss.incutio.com/?page=BoxModelHack */

Descriptions for Hex Color Values

Add comments with descriptive terms for hex color values to cut down on wasted time checking what colors they are equal to over & over.

#myDiv {
color: #000099; /* royal blue */
background-color: #f8f9ac; /* pale yellow */
border: 1px solid #e01914; /* red */
}

It is also helpful to comment in a table of all colors used on the site with a short description of the color’s general use as well:

/*

Hex Color Values
text #000099 royal blue
backgrounds #f8f9ac pale yellow
borders #e01914 red

*/

Table of Contents

Breaking the code down into sections grouped accordingly makes it easier to scan for what you are looking for, particularly when working with others who aren’t as familiar with your code as you are.

/*
TABLE OF CONTENTS
1 - Head
2 - Primary Navigation
3 - Secondary Navigation
4 - Main Content Area
5 - Footer
*/

/* #################### 1 - Head ################### */

#myDiv
{
margin: 0;
padding: 0;
width: 700px;
}

/* ############ 2 - Primary Navigation ############# */

#nav1
{
padding: 15px 0 5px 0;
clear: left;
border-bottom: 1px dotted #ccc;
width: 700px;}

Advertisements