How to Insert a CSS Comment

Including comments in your CSS code is useful and highly recommended.

Every website is made up of structural (which are dictated by HTML), functional, and stylistic elements. Cascading Style Sheets (CSS) are used to dictate the appearance—the "look and feel"—of a website. These styles are kept separate from the HTML structure to allow for ease of updating and adherence to web standards.

The Problem With Stylesheets

With the size and complexity of many websites today, stylesheets can become quite lengthy and cumbersome. This is especially true now that media queries for responsive website styles are an essential part of design, ensuring that a website looks as it should regardless of device. Those media queries alone can add a significant number of new styles to a CSS document, making it even harder to work with. This is where CSS comments can become an invaluable help to website designers and developers.

Comments Add Structure and Clarity

Adding comments to a website's CSS files is a great way to organize sections of that code for a human reader who is reviewing the document. It also ensures consistency when one web professional picks up where another leaves off, or when teams of people work on a site.

Well-formatted comments can communicate important aspects of the stylesheet to members of a team who may not be familiar with the code already. These comments are also very helpful for people who have worked on the site before but haven't recently; web designers typically work on many sites, and remembering design strategies from one to the next is difficult.

For Professionals' Eyes Only

CSS comments are not displayed when the page renders in web browsers. Those comments are informational only, just as HTML comments are (although the syntax is different). These CSS comments do not affect the visual display of a site in any way.

Adding CSS Comments

Adding a CSS comment is quite easy. You simply bookend your comment with the correct opening and closing comment tags:

  • Begin your comment by adding 
    /*
  • Close your comment by adding 
    */

Anything that appears between these two tags is the content of the comment, visible only in the code and not rendered by the browser. 

A CSS comment can take up any number of lines. Here are two examples:

/* red border example */
div#border_red {
border: thin solid red;
} 
/***************************
****************************
Style for code text
****************************
***************************/

Breaking Out Sections

Many designers organize stylesheets in small, easily digestible chunks that are easy to scan when reading. Typically, you'll see comments preceded and followed by series of hyphens that create large, obvious breaks in the page that are easy to see. Here is an example:

 /*----------------------- Header Styles ------------------------------ */

These comments indicate the start of a new section of coding.

"Commenting Out" Code

Because the comment tags tell the browser to ignore everything between them, you can use them to temporarily disable certain parts of CSS code. This can be handy when debugging, or when adjusting Web page formatting. In fact, designers often use them to "comment out" or "turn off" areas of code to see what happens if that section is not a part of the page.

To do this, simply add the opening comment tag before the code you'd like to comment out (disable); place the closing tag where you want the disabled portion to end. Nothing between those tags will affect the visual display of a site, allowing you to debug the CSS to see where a problem is happening. You can then go in and fix just that issue and remove the comments from the code.

CSS Commenting Tips

As a recap, here are some tips to remember for using comments in your CSS:

  1. Comments can span multiple lines.
  2. Comments can include CSS elements that you don't want a browser to render but that you don't want to delete completely. Remember to remove unused styles (as opposed to leaving them commented out) if you decide you do not need them on the website.
  3. Use comments whenever you write complicated CSS to add structure, clarify design decisions, and inform future developers (or remind yourself) about important considerations. This saves time in the future for all involved.
  4. Comments also can include meta information such as:
    1. Author
    2. Date created
    3. Copyright

Performance

While adding too many comments can affect a site's download speed and performance, you should not hesitate to use them. It would take many lines of comments to have a significant negative impact. Like so many aspects of web design, it all comes down to balance.

Original article by Jennifer Krynin; edited by Jeremy Girard