CSS Comments : A Tutorial

Comments in CSS are used to add explanatory notes or disable parts of the code without deleting them. They do not affect the rendered output and are ignored by the browser. Well-placed comments improve code readability, maintainability, and collaboration among developers.

This tutorial covers:

• Syntax of CSS comments
• Single-line and multi-line comments
• Best practices for writing comments
• Practical use cases

---

Syntax of CSS Comments

CSS uses /* */ to enclose comments. This format is used for both single-line and multi-line comments.

Example:

/* This is a comment */
p {
    color: blue; /* This is an inline comment */
}

Unlike programming languages like JavaScript or Python, CSS does not support // for single-line comments.

Types of CSS Comments

1. Single-Line Comments

A single-line comment starts with /* and ends with */. It can be placed above a CSS rule or within it.

Example:

/* This styles the heading */
h1 {
    font-size: 24px;
}

You can also place a comment at the end of a line:

h1 {
    font-size: 24px; /* This sets the heading size */
}

2. Multi-Line Comments

Multi-line comments span multiple lines, useful for providing detailed explanations.

Example:

/*
 This section styles the body
 Background color: light gray
 Font: Arial
*/
body {
    background-color: lightgray;
    font-family: Arial, sans-serif;
}

Best Practices for CSS Comments

1. Use Comments to Explain Complex Code

If a CSS rule is complex or affects multiple elements, adding a comment helps future developers (or even yourself) understand its purpose.

Example:

/* This creates a flex container that aligns items to the center */
.container {
    display: flex;
    justify-content: center;
    align-items: center;
}

2. Avoid Obvious Comments

Writing comments that simply restate the code without adding value should be avoided.

Unnecessary comment:

/* Setting the text color to red */
p {
    color: red;
}

Useful comment:

/* Error messages should be red to grab user attention */
.error-message {
    color: red;
}

3. Use Section Headers for Organization

For large stylesheets, grouping rules into sections with headers improves readability.

Example:

/* ============================= */
/*        HEADER STYLES          */
/* ============================= */
header {
    background-color: navy;
    color: white;
}

/* ============================= */
/*        FOOTER STYLES          */
/* ============================= */
footer {
    background-color: black;
    color: white;
}

4. Temporarily Disable Code with Comments

During debugging, you can comment out CSS rules instead of deleting them.

Example:

p {
    /* color: blue; */
    font-size: 16px;
}

This allows easy restoration if needed.

5. Maintain Consistency

Use a consistent commenting style throughout your project. If using uppercase section headers, apply them throughout.

Use Cases for CSS Comments

1. Documenting Custom Styles

If using custom styling that deviates from a framework’s default, explain why.

Example:

/* Overriding Bootstrap default padding */
.container {
    padding: 10px !important;
}

2. Marking TODOs or Fixes

For future improvements, leave TODO comments.

Example:

/* TODO: Improve mobile responsiveness */
@media (max-width: 600px) {
    nav {
        display: none;
    }
}

3. Identifying Sections for Easier Navigation

For large CSS files, use comments to separate sections.

Example:

/* === BUTTON STYLES === */
button {
    background-color: blue;
    color: white;
}

/* === FORM STYLES === */
input {
    border: 1px solid gray;
}