How to Insert a CSS Comment

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

Young woman working with wireless technology
Aping Vision/STS/Photographer's Choice RF/Getty Images

Every website is made up of structural elements (which are dictated by HTML) as well as the visual style or "look and feel" of that site. Cascading Style Sheets (CSS) are what is used to dictate the visual appearance of a website. These styles are kept separate from the HTML structure to allow for ease of updating and adherence to Web standards.

With the size of complexity of many websites today, style sheets can quickly become quite lengthy and very cumbersome to work with.

This is especially true when you start adding in media queries for responsive website styles. Those media queries alone can add a significant amount of new styles to a CSS document and making it even harder to work with.  This is where CSS comments can become an invaluable help on a website.

Adding comments to a website's CSS files is a great way to add structure to sections of that code for a human reader who is reviewing the document. It is also a wonderful method for explaining those styles for a web professional who may have to work on the site in the future - including yourself! 

In the end, smartly added CSS comments will make a style sheet easier to process. This is, indeed, important for style sheets that will be edited by teams. Comments can be used to communicate important aspects of the style sheet to different members of the team who may not be familiar with the code already. These comments can also be very helpful for people who have worked on the site before if they get back into the code after being away from it for some time.

I have often had to edit a website I built months or even years ago and having well formatted comments in the HTML and CSS is very welcome help!  Remember, just because you built a site does not mean you will remember why you did the things you did when you return to that site in the future! Comments can make your intentions clear and clear up any misunderstandings before they even happen.

One thing to understand about CSS comments is that they not displayed when the page renders in web browsers. Those comments are informational only, just like HTML comments are (although the syntax is different between the two). These CSS comments do not affect the visual display of a site in any way and are simply present in the code itself.

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 will be the content of the comment, visible only in the code and not rendered by the browser. 

A CSS comment can be a single line, or it can take up multiple lines. Here's a single line example:

div#border_red {

    border: thin solid red;

    } /* red border example */

And a multiline example:

/***************************
****************************
Style for code text
****************************
***************************/

Breaking Out Sections

One of the ways I often use CSS comments is to organize my style sheet in smaller, more easily disgestible chunks. I like to be able to easily see these sections when I peruse the file later.

To do this, I often add comments with lots of hyphens in them so that they provide large, obvious breaks in the page that are easy to see as I quickly scroll through the code. Here is an example:

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

When I see one of these comments in my code, I know it is the start of a new section of that document, allowing me to more easily process and use the code.

"Commenting Out" Code

Comment tags can also be useful in the actual process of coding and debugging a page.  Comments can be used to "comment out" or "turn off" areas of that code to see what happens if that section is not a part of the page. 

So how does this work? Well, 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.

To do this, you would simply add the opening comment tag where you want the code to start being disabled and then place that ending tag where you want the disabled portion to end. Everything between those tags will not affect the visual display of a site, allowing you to debug the CSS to see where a problem may be 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 rendered by a browser, but don't want to delete completely. This is a nice way to debug a website's style sheets - just be sure 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 clarification and to inform future developers, or yourself in the future, about important things they should know. This will save future development time for all involved.
  4. Comments can also include meta information like:
    • author
    • date created
    • copyright information

Performance

Comments can certainly be helpful, but be aware that the more comments you add to a style sheet, the heftier it will become, which will affect a site's download speed and performance. This is a real concern, but you should not hesitate to add helpful and legitimate comments for fear that performance will suffer. Lines of CSS do not add substantial size to a document.  You would need to add TONS of lines of comments to make a significant impact on the size of the CSS file.  Adding a handful of useful comments into your CSS should not give you a net negative impact on page speed.

In the end, you will want to find the balance between helpful comments and too many comments to get the benefits of both in your CSS documents.

Original article by Jennifer Krynin. Edited by Jeremy Girard on 7/5/17