Obsessive CSS Code Formatting: Organization, Comments, and Signatures

One of my favorite aspects of producing clean, well-formatted CSS code is “meta-organizing” the document using comments. In CSS, comments are included in the stylesheet like so:

/* i am the walrus */

When used constructively, CSS comments serve to break down documents into distinct regions, provide key information about specific declarations, and bring order to even the most complex stylesheets. In my experience, a well-commented stylesheet improves efficiency and optimizes comprehension.

Working with CSS, you can add comments any way you want. There are many different ways to use CSS comments, and endless ways to get there. Let’s check out some practical and interesting ways to use comments, along with some creative ways of doing so.

Information about specific code

Surely the most common reason to use comments involves explaining various CSS rules. Especially helpful for unusual or unexpected code, explanatory comments generally are kept brief, look similar, and vary in location:

/* example border */
div#example_01 {
	border: thin solid red;
	}
div#example_02 {
	font-weight: bold;
	margin: 3em 0;
	_margin: 1em; /* IE6 hack */
	color: red;
	}

The obsessive-compulsive part of this type of commenting involves stripping down the explanation to a bare minimum. Instead of writing “some browsers get this, but not internet explorer”, I write, “non-IE only”. Additionally, I avoid using capital letters except when referring to acronyms. This helps maintain the flow of an otherwise entirely lowercase document, however I have also seen effective use of the crazy ALL CAPITAL LETTERS approach. And finally, only the opening (/*) and closing (*/) comment characters are included with the actual comment, along with a single space on either side. Taken together, these three techniques help keep these types of explanatory comments light, clean, and easy.

Organizing regions of code

An excellent way to stay organized when writing CSS is to group associated code blocks together in a way that is consistent and logical. For example, I generally break things down along the lines of:

• global settings (resets, scrollbars, etc.)
• primary layout structure (body, primary divs)
• secondary layout structure (header, footer, sidebar)
• tertiary layout structure (page regions, floats)
• text-related treatments (headings, paragraphs, lists)
• images, links, and other salient features (pre, code)
• general styles (forms, tables, buttons, acronyms et al)
• general classes (.clear, .center, .right, .left, etc.)
• miscellaneous stuff and template code

Then, to organize such a stylesheet, each region would be clearly indicated with some sort of distinguishing comment. Although I tend to keep it simple with something along these lines:

/* === GLOBAL SETTINGS === */

..I have seen (and used) a variety of creative sectional comments:

/* GLOBAL SETTINGS
   ----------------------------- */


/* GLOBAL SETTINGS
   ============================= */


/* ==[ Global Settings ]== */


/* [[[ Global Settings ]]] */


/*** GLOBAL SETTINGS ***/


/* ===============
   GLOBAL SETTINGS 
   =============== */

..and the list goes on and on. Really, the only requirements for any CSS comment are the opening and closing characters — everything else is entirely up to you. In my stylesheets, I try to keep the sectional comments as obvious and recognizable as possible without interrupting the overall flow of the document. Generally, I like to include a few equality signs (“===”) and capitalize the entire comment to distinguish regional comments from the more specific variety targeting selectors, declarations, hacks, etc.

Navigating extensive stylesheets

For extensive or highly complex stylesheets, CSS comments can also be used to implement a “quick-jump” mechanism to facilitate easy navigation. By including a specific character within sectional comments, you provide a way to “jump” through the document by using your software’s inevitable “Find” feature. For example, with the following sectional comments dispersed throughout my stylesheet, it would be very easy to jump from one section to the next with a simple Find("=") command:

/* ===GLOBAL=== */
.
.
.
/* ===PRIMARY=== */
.
.
.
/* ===HEADER=== */
.
.
.
/* ===SIDEBAR=== */
.
.
.
/* ===FOOTER=== */
.
.
.

When doing this, it is important to choose a navigational character that is not used elsewhere in your CSS document. You may also want to use a CSS comment to include an organizational directory near the top of the document, thereby facilitating quick and easy stylesheet navigation:

/* CSS DIRECTORY
	1. =GLOBAL
	2. =PRIMARY
	3. =HEADER
	4. =SIDEBAR
	5. =FOOTER
*/

You could even include a key character within specific comments and hacks. Although I have never seen anyone use this technique, it is easy to imagine how something like this would be useful:

/* HACK DIRECTORY
	% box model hack
	$ targets safari
	& clearfix hack
	? targets IE 7
*/

..with the associated anchors also present within the comments themselves. The same line of thinking could be applied to nearly any important aspect of a stylesheet. Something like this would certainly help collaborators and clients understand and navigate the document.

Other remarkable uses for the humble comment

Okay, the article is getting rather long, so I will try to wrap it up. Here are some other great ways to use comments to improve the informational value of your stylesheets..

Timestamp and document information

An excellent way to stay organized on the team or network level, especially useful during periods of rapid collaboration or development. In addition to this example, check out the top several lines of just about any WordPress theme for an excellent “real-world” implementation.

/* DOCUMENT INFORMATION
	- Document: Jukebox Theme
	- Version:  1.2.3
	- Client:   Fonzi Winkler
	- Author:   M. Gibbonz   
*/

Color and font information

In an effort to streamline production and subsequent editing, I have adapted this excellent strategy for summarizing all of the colors and fonts used in the stylesheet. This practice has served me well on countless occasions.

/* COLORS
	- default body text  #ffffcc
	- subtitle h2 text   #ff9900
	- form input borders #cc9933
	- default p text     #f0f0f0
	- pre borders        #ffff99
*/

/* FONTS
	- default body text  Arial, Helvetica Neue, Helvetica, sans-serif
	- subtitle h2 text   Garamond, Hoefler Text, Times New Roman, Times, serif
	- form input text    Cambria, Georgia, Times, Times New Roman, Times, serif
	- default p text     Copperplate Light, Copperplate Gothic Light, serif
	- pre and code       Consolas, Lucida Console, Monaco, monospace
*/

Trademark signatures, quotes, slogans

Gotta have ‘em! Well, maybe not, but I certainly enjoy the opportunity to express myself creatively. For the past four or five years, my personal CSS signature thing has been this:

/* all your code are belong to poetry */

..which is placed at the end of every stylesheet. Although I cannot remember them now, over the years I have seen a good number of interesting signatures, including everything from song and movie quotes to personal thoughts and nonsense. If any of you have your own personal signature thing, I would love to hear it!

Time for some comments!

CSS comments are versatile and flexible enough to handle even the longest of fangs. Embellishing your stylesheets with informational and organizational comments is an excellent way to improve the overall quality of your CSS documents while enhancing usability and efficiency. Hopefully, this article will inspire some new ways for you to use comments in your next CSS adventure. Until then, tell us about your different CSS commenting techniques! New ideas, variations, improvements, styles — anything!

About the Author

Jeff Starr = Web Developer. Security Specialist. WordPress Buff.