CSS Comments: Best Practices to Comment Like a Pro - Position Is Everything (2024)

CSS comment lets you add comments that organize or explain various segments of the stylesheet.

Although adding comments on CSS may seem extraneous when coding, it is extremely useful when redesigning or debugging a website.

Comments in CSS tell the reader the purpose of specific lines of CSS, and such insights are useful especially when multiple developers work on a website. Read on to learn how you can comment like a pro.

How to Comment in CSS

Commenting in CSS helps explain a block of code or even make temporary changes while developing websites. Browsers do not execute commented CSS code.

In CSS, comments can either be single or multi-line and they all start with /* and terminate with */. With these style sheets, developers can add as many comments as they want. Moreover, it is possible to style the comments to make them more readable.

By simply adding a text inside the /**/ you tell the browser these are notes in CSS and should not be executed. Just like programming languages that rely on the /* */ syntax for comments, you cannot nest CSS comments. It means that the first occurrence of */ after a /* terminates the comment.

The single-line comment is the most common CSS comment format.

– Example – Single-Line CSS Comments

How to Comment Out CSS

Besides explaining what the CSS code does, comments in CSS provide a way to comment out CSS or invalidate CSS ruleset. Commenting out CSS tells the browsers not to execute that styling.

– Example – Commenting out CSS Using Single-line Comment

Using the previous example, we can comment out the font color as shown below.

– Example 2 – Commenting out CSS Using Multi-line Comment

Also, it is possible to comment out the entire ruleset as follows.

Adding notes in CSS

Comments make it easy to add explanatory notes. Using as little as one CSS comment line, can make it possible for you to add notes next to the CSS.

– Example

Note: CSS Comments do not interfere with the interpretation of other parts of the stylesheet. As well, they do not affect the front-end layout of a website. What’s more, they are easy to add even for beginners. You can place comments anywhere in the stylesheet where white space is allowed.

Organizing CSS Using Comments – For Large Projects

In huge projects, CSS files tend to be large in size which makes maintaining them difficult. So, organizing CSS code into sections is helpful because it makes it easy to find specific rules even after finishing the project.

Whenever possible, you should group various stylesheet sections using comments and separate one section from another using new lines. Putting comments for each group of CSS code provides an easy way of locating the CSS group when editing.

– Organizing CSS Comments: Example

Techniques To Improve CSS Code and Comment Structure

Using sensible code structure is advisable since it makes it easy to understand the CSS code years later. Comments drastically decrease the complexity of understanding CSS code. Below are the techniques developers use to comment and simplify maintenance of CSS code, and now you can use them in your code too!

– Divide and Conquer

Establish the most important aspects and the layout of the CSS code and group common elements inside sections and give each group a title. For instance, in large projects, developers may have to import external CSS files. So, clearly separate code fragments using comments. Use more * symbols to make the heading of each section in a stylesheet more visible.

CSS Comments: Divide and Conquer Example

Such sections make it easy to immediately recognize individual blocks while scanning through the code. The divide and conquer approach may not work for large projects since one file may become too big.

For large projects, you might need to divide the code into multiple files to make it easy to see groups of code fragments. In such cases, the master stylesheet has the role of importing groups.

Using a master stylesheet results in a clean code that is easy to understand and maintain. However, it causes unnecessary server requests, so keep that in mind if you want to use it.

CSS Comments: Master Stylesheet Example

– Defining a Table of Contents

Having a table of contents in a stylesheet helps with the overview of the structure of the code. Through CSS comments, you can include a table of contents that shows a tree overview of the layout. You can rely on some keywords like content group or header section to make it easy to navigate.

What’s more, specific elements that likely require often updates after finishing the project can be part of the table of contents. This way, it becomes easier to find them without scanning the entire code. One way of adding a table of content is through simple enumeration as shown below.

Using the example below, jumping to the Sidebar section is easy using the search tool to find 4. Sidebar. It is fast and effective.

CSS Comments: Defining a Table of Contents Example

Also, it is possible to use CSS comments to create an indented table of content. Defining a table of contents makes it easy for others to read and comprehend your CSS code. It is especially useful when working in a team since it saves a lot of time.

– Defining Custom Typography and Colors

CSS comments provide a way of quickly referencing variables like custom colors and typography. Often, web development considers typography and colors as constants. Since CSS does not have constants, developers use CSS comments to define some at the top of the CSS file.

Usually, developers use comments to come up with a color glossary. As such, it gives them a quick reference to colors they use on a website to avoid mistakes. Also, it gives them a quick list of colors that they can change if necessary.

Example 1 – Defining Custom Colors Through CSS Comments

Moreover, developers use the same approach to define typography. They use CSS comments to include important notes that help comprehend the thinking behind the definitions.

Example 2 – Defining Custom Typography Using CSS Comments

– Using Keywords in Comments – For Better Overview of New Changes

One interesting way developers can highlight recent changes to their CSS code is through CSS comments. Apart from indenting changed or new lines in a CSS file, developers can use keywords such as @new. This allows them to navigate to the keyword and remove changes that cause issues during execution.

CSS Comments: Using Keywords in Comments Example

Comments in code are important. So, take time to explain components, their function, limitations, and how they are built. Avoid a scenario where others have to guess the purpose of uncommon CSS code. The comment style needs to be consistent and simple.

• Whenever possible place comments in a new line above the subject
• Ensure the length of the line is sensible
• Use comments to break CSS code into sections

Conclusion

Commenting in CSS helps developers achieve sensible structuring by leaving useful notes and hints that are useful. In this article, you will find out examples on how to adopt CSS comments so that you can:

• Add comments to complex code
• Organize CSS code
• Assist others to comprehend your strategy and thinking
• Understand your code in future
• Make it easy to find changes
• Define custom color and typography

The goal of comments in CSS is to have a code that is easy to read and maintain. Using CSS comments saves you and anyone who reviews your code a lot of trouble. If you keep practicing it long-term through our guide, that will help you understand the code years later when you go through it.