Document Your CSS Like You Are Working on a Team

Written by Chris Coyier from CSS-Tricks on December 28, 2007

Commenting your CSS is simple, just put them in between “/*” and */”, like so:

p {
   font-size: 1.3em;  /* Font size for main content */
}

That’s a single line comment, but you can do multi lines just as easily:

/*
  Blog Design Template Author:  Chris Coyier
  Authors Website: css-tricks.com

  Feel free to use, share, or alter this
  template in any way.
  Links are always appreciated.
*/

There are many different schools of thought on the use of comments. On one extreme, some people think they are just a waste of time and unnecessarily increase CSS file size. CSS isn’t that complicated of a language, after all. Why clutter it up with comments? The other extreme is going nuts with your comments and commenting every section and attribute. There are even organizations out there trying to standardize CSS commenting.

As with most things in life, I think the sensible solution is to use comments modestly where it really makes sense. In other words, use CSS comments to document your work like you would if you were working on a team. Here are some quick examples of where commenting can come in handy and really help others when looking at your CSS for the first time.

Explain your colors

#sidebar li {
   color: #fffea4;  /* Light Yellow */
}

Explain important positioning

#hangtab {
   position: absolute;  /* This keeps the hangtab */
   left: 0; top: 20px;  /* in the upper right corner */
}
.wrap {
   margin: 0 auto; /* This keeps the page content centered */
}

Explain hacks

.post {
   min-height: 500px;
   height: auto !important;   /* min-height hack for IE */
   height: 500px;
}

Explain Sections

/*  START NAVIGATION */
#nav {
   background: blue;
   padding: 10px 0 10px 0;
}
/* END NAVIGATION */

/* START TOOLBOX */
.clear { clear: both; }
/* END TOOLBOX */

To be perfectly honest, I do use CSS commenting in my own work, but I use it pretty lightly. What I do is document rules that I know are particularly important for layout or are weird/quirky for any reason. Does anyone else have any thoughts on how to best use CSS commenting?

Share and Enjoy: