02 Mar March 02, 2015

Save Time and Frustration by Documenting Your CSS

Josh Sholder 6 Coding, CSS, Productivity, Tutorial

The Golden Rule:

Well organized and documented CSS can save you hours of potential frustration in both the short and long game.

CSS Comment Header
Using CSS (cascading style sheets) to style your website is an important skill for anyone who wants control over their websites presentation. If you are new to CSS be sure to check out the Further Down the Rabbit Hole section at the bottom of this post. There you will find some useful resource links for getting your feet wet with CSS.

In today’s post we thought it might be helpful to share how we organize our Custom CSS file in relation to the Business Advantage theme. The information should be applicable to any situation that relies on CSS to alter presentation. We also include a couple tips that help in troubleshooting and maintaining your CSS rules.

Comments – Why CSS Documentation is Vital

Comments allow you to add documentation to your CSS code. At its heart, well commented code will help you easily identify how a particular CSS rule affects the presentation of your site. This is a great time-saver when you are fine-tuning your work but can also be a godsend when you return to the code months later. Returning to undocumented code you haven’t even thought about for six months can be a serious nightmare.

The actual structure of a CSS comment is very easy. Browsers ignore any text in a CSS file wrapped in /* */. Everything between the opening and closing tags is simply skipped over by the browser interpreting the code. Consider the following:

/* This is an example of a CSS comment */

“This is an example of a CSS comment” would be overlooked by the browser and have no affect on the corresponding site presentation.

How We Use CSS Comments at Michael the Tech Guy

We learned the hard way about documenting our CSS – that is, we learned of its importance after returning to work with existing uncommented CSS. It didn’t take us long to realize the importance of something that seemed so minor at first glance.

We start by breaking the CSS code into sections. Remember, our examples are from sites created with the Business Advantage theme, but the practices apply to any use of CSS. By keeping code that affects specific parts of the site together, we can more easily drill down to the actual rules we need. In addition, we take the time to document each individual CSS rule. Sometimes we even add comments to components of specific rules when necessary.

Commented Section Example:

/* ========== Header Section ========== */

Looking more specifically at individual code snippets, comments can be used to identify the actual change your snippet is creating. In the example below we have added a comment above the CSS snippet to quickly identify it.

Commented CSS Rule Example:

/* Set Global Text Color */
body {
color: #000000 !important;

Commented Rule Specific Example:

body {
color: #000000 !important; /* Black */

CSS Section Comments – A Framework to Consider

Here are the section categories we use when organizing our CSS:

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

/* =============== HEADER ========================= */

/* =============== MENU BAR ======================= */

/* =============== RESPONSIVE MENU =============== */

/* =============== FOOTER ======================== */

/* =============== PLUGINS ======================== */

/* =============== TEST AREA BELOW ================ */

Power of the Test Area

You may have noticed the title of our last CSS Category is labeled “Test Area Below”. Mike and I wanted to touch on this briefly as we have found it to be a helpful diagnostic tool. We use this area to test out any new or changed code for our sites.

The cool thing about the test area is you can alter existing CSS in the test area and, since it appears at the bottom of the file, it will take precedence. This assumes the CSS selectors for both rules have the same specificity.

Once the rule is working as we want, we comment it and move it out of the test area into its appropriate category in the CSS file. It’s important to note that if you are working on changes to an existing rule you will want to replace the old CSS rule with your new rule. You don’t want to have multiple occurrences of the same CSS rule in your file.

Following this tip has saved us hours.

Using Comments to Disable Lines of Code

Comments also come in handy for temporarily blocking out lines of CSS code when you are troubleshooting. Instead of removing the entire CSS rule (or block of rules) you can carefully comment them out to temporarily turn off their effects in the sites presentation.

In the following example we are commenting out the “font-size; 14px;” line. The comment tells the browsers to ignore the content between the open and close comment.

/* Set Global Text Color and Font Size */
body {
color: #000000 !important; /* Black */
/* font-size: 14px; */

How This Can Help You

Documenting your CSS code with comments does add additional steps during development. We have found that the amount of time, it saves you in the long run, is an exponential savings in comparison.

Mike and I wanted to share a CSS cheat sheet of some of the CSS code snippets we use with Business Advantage. If you are new to customizing the BA theme, it would work as a wonderful cheat-sheet to get you started. If you don’t use BA this sheet will still be helpful in demonstrating how to organize and comment your CSS files. Please note, we have added some commented sections to our CSS cheat sheet that will not appear on the structure listed on this post.

Download our BA CSS Cheat Sheet

Further Down the Rabbit Hole


If you are interested in learning more about CSS and all the wonderful things you can do with it, please visit the following links.

Read our CSS 101 and CSS 102 blog posts for our introduction into CSS.
CSS 101
CSS 102

W3Schools is our go to resource for all things CSS. Below is a link to their CSS tutorial.
W3Schools CSS Tutorial

Nothing makes us happier at Michael the Tech Guy than when you take the time to read our blog. Documenting your CSS rules can end up being a huge boon for productivity. If you have any comments, questions or requests for new blog topics, please contact us at mmurphy65@gmail.com

We Invite You To Share Our Work Freely:


6 thoughts on “Save Time and Frustration by Documenting Your CSS

  1. Dale Johnson says:

    Using comments like this can also save incredibly when you have to modify some standard file, so that you can find the change that needs replicating later. Nice article; thanks. –Dale

    1. Michael Murphy says:

      Thanks for the kind words Dale.

  2. Sandra says:

    Excellent points. This may be old school for some, but when you’ve been around the block, you’ll appreciate /* comments */ as the memory wares thin. 🙂 Thanks for bringing this very important feature to light. It’s just good professional practice.

    1. Josh Sholder says:

      Thank you both Sandra and Dale for your input. We appreciate the support.

  3. You are right on point! I’ve been working on a multisite for a few weeks and just spent an hour tidying up and commenting my css. I know when I’m tossing the rules in that I should comment as I go but I always wait until after. (It’s ridiculous – so much easier to comment as you go). I’m working with SmallBiz Dynamic child themes mostly but I will be checking out your BA cheat sheets too! Nice job, guys, and thank you!

  4. Michael Murphy says:

    Thank you for the kind words Julie. All the tips Josh shared in this post we learned the hard way, believe me! 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *