Beginner’s Guide to CSS Comments

Have you ever come back to a CSS project and felt completely lost while looking at your own code? 

• What are these tweaks for?

• Why did you adjust this?

• What's this connected to?

It’s easy to forget what's going on and make mistakes when editing. And it’s not because you forgot CSS, it’s because style sheets don’t explain themselves.

Fortunately, there’s a simple habit that can change that. It’s something employers and development teams look for, and it can make your work stand out for all the right reasons. It doesn’t affect how your site looks, but it can save hours of confusion later.

In this guide, I’ll walk you through how comments work, the differences between comments in CSS and other languages, practical ways to use them, and the common mistakes to avoid. 

Sidenote: Want to take your web design to the next level? Check out my complete CSS course:

Intermediate

The CSS Bootcamp: Zero to Mastery

42 Hours •238 Lessons

Learn everything from CSS basics to advanced CSS techniques by completing 100+ exercises and projects that will wow users and prospective employers. Become a CSS Pro and create beautifully designed apps.

Jacinto Wong

Learn everything from CSS basics to advanced CSS techniques by completing 100+ exercises and projects. You'll learn how to use CSS to create beautiful, responsive websites that wow users and employers. Become a CSS Pro and never create an ugly website again.

With that out of the way, let’s get into this 5-minute tutorial…

What are CSS comments and why should you use them?

A comment in coding is kind of like a Post-it note that you leave inside your code. It doesn't affect the code itself or show up in the browser. It’s just there so that the person checking out the code can understand what’s happening more easily.

It’s such a simple thing to use, but trust me when I say that using comments can save you from a lot of frustration. 

For example

Imagine your project already has a global button style that works fine everywhere, except on the homepage hero section, where the layout shifts slightly and makes the button look off-center. 

So rather than changing the global style and risking breaking buttons site-wide, you might add a specific rule just for that section:

.hero button {
    padding: 14px 24px;
}

It works and everything is fine. 

But then 12 months pass, and something breaks this, and you’re not sure what's going on. So you have to open up all your code, scan through hundreds of lines to find this section, and then try to figure out why you had even done this in the first place.

That would suck, right?

The better solution would be to simply add a comment explaining what you did in this code block, so that you can find it easily, and then figure out how to apply the fix.

/* Extra padding for homepage hero button alignment */
.hero button {
    padding: 14px 24px;
}

Handy, right?

It's even more useful when you’re working on a team and other people may have to inspect and fix the code, which is why team leads and employers love coders who have this habit.

So let’s look at how to do this.

How to use CSS comments

Writing a CSS comment is actually really simple, as there’s just one comment style. You use /* at the start of the comment, and */ at the end, like so:

/* This is a comment */
body {
    background-color: #f9f9f9;
}

And you can put it anywhere you write CSS, such as inside a .css file, in a <style> tag in HTML, or even in CSS written inside JavaScript.

However, if you’ve used other programming languages, you might be expecting // for quick single-line notes, or # for shell-style comments, but CSS doesn’t have those. There’s only one syntax and you use it for everything. 

The reason for this goes back to when CSS was first created in the mid-90s. The language was designed to be simple for browsers to read, and the /* */ format was already widely used in other languages like C. Sticking to one consistent syntax made it easier for browsers to support and for developers to learn, and that simplicity has stuck ever since.

So yeah, comments are super simple to add. That being said, there are some good habits you should get into when you use them.

5 common ways to use CSS comments

Single-line comments

A single-line comment is a quick note that sits above or next to a single rule. It’s perfect for short explanations where the meaning might not be obvious from the code alone.

For example

In this codeblock, the comment tells you why that specific spacing exists, so a future edit won’t accidentally break the intended visual alignment:

/* Match hero title height to background image crop */
h1.hero-title {
    margin-top: 3rem;
}

Multi-line or block comments

Sometimes you need more than a few words because you’re explaining a tricky layout, describing how styles interact, or leaving instructions for future changes. In those cases, you can spread your comment over multiple lines.

For example

If we go back to the previous example, we might want to add an extra line to give more context. Perhaps we need to remember to tweak this if something else changes:

/* 
Match hero title height to background image crop.
Adjust this margin if the hero image or typography changes,
as spacing is tightly linked to the current design.
*/
h1.hero-title {
    margin-top: 3rem;
}

This not only gives the “why” behind what the code is doing, but also a note on what it impacts, making it less likely that a future edit will break the layout.

Not only that, but breaking a longer comment into lines like this also makes it easier to scan!

Section dividers or documentation comments

While multi-line comments help with complex explanations, sometimes you just need a quick way to break up your stylesheet visually, and that’s where section dividers come in. They’re not really a comment as such, but a handy little trick for when your stylesheet gets long.

The trick is to use comments as visual markers to separate different sections. This makes it much easier to navigate, like so:

/* =========================
   Header Styles
========================= */

header {
    background: #fff;
    padding: 20px;
}

Inline comments next to rules

Although we usually write comments above the code block that they are referring to, it is ok to place a comment on the same line as a property. 

However, this is usually only done when you want to clarify why a specific value is used without breaking the flow of the CSS.

button {
    padding: 14px 24px; /* Extra space for better tap targets on mobile */
}

Unstripped comments

Most build tools strip out comments when they minify your CSS and that’s usually what you want, since comments are for developers, not end users.

However, sometimes you might want a comment to survive all the way to production like if you want to include a license notice or credit in your distributed CSS.

For example

/*! 
  Theme CSS v1.2.0
  Copyright 2025 Example Co.
  Licensed under MIT
*/

It’s super easy to do, all you have to change is add an exclamation mark right after the opening */! .

Common mistakes and best practices

As you can see, comments are fairly easy to use. However, there are some common mistakes that pop up now and again. Especially with beginners or with people used to writing code in other languages.

So let’s look at the common issues and how to fix them.

#1. Overusing comments

It can be really common when you first learn about comments to then go overboard and add them everywhere. The reality though is that if you’re explaining every single rule, the comments stop being useful and start being noise. 

/* Select the card element */
.card {
    /* Set the width of the card */
    width: 300px;
    /* Add a 1 pixel solid gray border */
    border: 1px solid #ccc;
    /* Add padding on all sides */
    padding: 16px;
    /* Add rounded corners */
    border-radius: 8px;
    /* Add a shadow effect */
    box-shadow: 0 4px 8px rgba(0,0,0,0.1);
} /* End of card styles */

/* Select the card title */
.card-title {
    /* Set the font size to 24 pixels */
    font-size: 24px;
    /* Set the color of the text */
    color: #333;
    /* Add space below the title */
    margin-bottom: 12px;
} /* End of card title styles */

How hard is that to read!?

So make sure to only use them to clarify unusual choices, constraints, or tricky logic.

/*
  Card Component
  A versatile container for displaying content snippets.
*/
.card {
    width: 300px;
    border: 1px solid #ccc;
    padding: 16px;
    border-radius: 8px;
    box-shadow: 0 4px 8px rgba(0,0,0,0.1);

    /* Required to ensure the card's shadow appears correctly
       above the overlapping footer element on mobile. */
    position: relative;
    z-index: 2;
}

.card-title {
    font-size: 24px;
    color: #333;
    margin-bottom: 12px;
}

#2. Explaining what and not why

Your comments should help you understand why something is happening and not just what.

For example

Writing /* Remove margin */ in the following code block is redundant because the property name already tells you that.

/* Remove margin */
margin: 0;

/* Reset heading margin to align with logo baseline */
margin: 0;

Isn’t that better?

Now anyone reading this comment knows why the change was made and when it might be safe to alter it.

#3. Forgetting to end a comment!

CSS doesn’t have “auto-closing” comments like some languages, so if you start a comment with /* but forget to end it with */ , everything after it will be treated as part of the comment and not work as expected.

For example

/* This will hide the background color  
body {
    background: #f9f9f9;
}

How to avoid it:

• Always double-check for both the opening /* and closing */

• If you’re adding a quick comment, type both first and then fill in the text between

• Most code editors can auto-close comments so make sure to turn that setting on if available

#4. Trying to nest comments

You can’t nest comments inside each other with CSS, as the browser will stop at the first */ it finds, even if that’s not the one you meant to close. 

For example

/* Outer comment starts */
/* Inner comment — just noting a tweak */
padding: 20px;
/* Outer comment ends */

You might expect the inner comment to work, but the browser will close the comment at the first */ and treat the rest as normal CSS, likely causing layout or syntax errors.

A better approach is to keep comments separate and on their own lines.

However, if you want to try and emulate nested comments, you could simply just add extra lines after the comment and style them so they seem like nested points, like so:

/*  
Outer comment: Button layout rules  
- Padding adjusted for touch devices  
- Matches global primary button style  
*/

#5. Including sensitive information

Avoid putting internal URLs, emails, or other sensitive info in comments, because if your CSS is public, then so is that data!

For example

/* Contact Jane at jane@example.com if this breaks */

Or even worse:

/* Internal API endpoint: https://internal.example.com/api */

Best practice is to keep comments technical and neutral, and put private details in your team’s tracker instead.

#6. Not tagging important notes

Another handy way to use comments is to make note of changes in code or tasks to complete by using tags like TODO, FIXME, or NOTE. 

The key though is to make sure you pair them with a clear action and context, as this makes it easy to search for and clean up later.

/* TODO: remove IE11 fallback once analytics shows <0.5% usage */

If you didn’t add that, you would have to stop and think about what it is that you need to do.

#7. Letting comments get out of date

Likewise, an outdated comment can be more harmful than no comment at all because it sends the wrong signal. 

For example

If a note says a rule fixes a bug that no longer exists, then someone might keep that code unnecessarily. 

A good habit would be that whenever you touch a block of CSS, read the nearby comment. If it’s no longer true, update it or remove it. And if you delete a workaround, delete the comment that justified it. 

Basically, treat comments as living parts of the code, not one-time notes.

#8. Inconsistent formatting

Mixing short notes, long paragraphs, and different divider styles makes a file harder to scan so make sure to pick a standardized style for comments and stick with it:

• Same divider format

• Same line length

• Same spacing

• Etc

If you’re on a team, agree on this once and add a brief example at the top of your main stylesheet so that everyone stays consistent.

#9. Leaving commented-out code for too long

Another way you can use comments is to ‘comment out’ code that you’re not using.

For example

Here you can see that the background color for the navigation has been temporarily commented out:

/* nav {
    background-color: #333;
    color: #fff;
} */

Of course, the problem is when you never come back to clean this up because it clutters the file and makes readers wonder if it’s still needed. So if you must keep it for a short time, add an expiry note:

/* Temporarily disabled for v2 nav refactor (remove after 2025-09)
nav {
    background-color: #333;
    color: #fff;
}
*/

Time to make your own code easier to remember!

CSS comments might be a simple habit, but they have a big impact on how easy your styles are to read, maintain, and share. A few well-placed notes can save you hours of confusion, or prevent someone else from undoing your hard work.

However, just because they’re easy to use, you’ll never learn them properly until you apply them to your own code, so go ahead and try adding some comments to your own CSS today. 

Start small, focus on explaining why your code exists, and see how much smoother it feels to work with your stylesheets over time.

P.S.

Remember, if you want to learn more about CSS + HTML, then check out my complete CSS course:

Intermediate

The CSS Bootcamp: Zero to Mastery

42 Hours •238 Lessons

Learn everything from CSS basics to advanced CSS techniques by completing 100+ exercises and projects that will wow users and prospective employers. Become a CSS Pro and create beautifully designed apps.

Jacinto Wong

You’ll learn everything from CSS basics to advanced CSS techniques by completing 100+ exercises and projects. You'll also learn how to use CSS to create beautiful, responsive websites that wow users and employers. 

Even better?

Once you join, you’ll get access to our private Discord community, where you can ask questions and get answers from me, other students, and other working tech professionals.