HTML comments are notes that you can add to your HTML code that won’t be displayed on the page when it’s loaded. They’re a great way to keep track of what you’re doing in your code, or to leave yourself reminder notes about how the code works.
How to use HTML comments
HTML comments start with <!-- and end with --> . Anything between those two markers will be ignored by the browser. You can use HTML comments to hide parts of your code while you’re working on it, or to add notes to yourself or other developers.
Comments are also helpful for explaining complicated code snippets to others.
The benefits of using HTML comments
One of the main benefits of HTML comments is that you can leave quick notes to yourself or someone else working on the code. If you find a rather complex situation, you can clearly describe what is going on, in-line. Or, if you simply want to describe or split up parts of your code, comments are a great way to do that.
Here’s are some example!
<!-- We need to preconnect to Google Fonts because it can improve performance -->
<link rel="preconnect" href="https://fonts.gstatic.com/" />
or
<div class="p-4 bg-gray-100 rounded">
<p>Here's a paragraph of text</p>
<!-- Visitors need to be signed in before seeing this content. -->
<!-- A class will be added to the body when a user signs in. -->
<p class="hidden-when-signed-in">Here's another paragraph of text</p>
</div>
Tips for creating effective HTML comments
When you’re writing HTML comments, it’s important to keep a few things in mind. Here are some tips to help you write effective comments.
Keep it short and sweet
Comments should be short and to the point. You don’t need to write a novel about what you’re doing. If you need to explain something in more detail, you can always add a link to a blog post or documentation page.
There is a judgement call here because there’s no length recommendation. Be long enough where you think you can be helpful. You want your comments to be clear and easy to understand.
Use proper grammar and spelling
Spelling errors and bad grammar can be unprofessional. If someone reads your code and your comments look like a 5th grader wrote them, they might not take you seriously. Unless, of course, you’re a 5th grader.
Use proper indentation and formatting
Indent your comments to match the indentation of the code that they are commenting on. This makes it easier to read. It’s also helpful to only have a few words on each line. If you have long sentences and the commenting isn’t broken up, it can be hard to read for someone that doesn’t have word wrapping enabled on their IDE.
When not to use HTML comments
There are some situations where you shouldn’t use HTML comments. Here are a few examples:
Don’t use HTML comments to hide code from the browser
If you need to hide code, use the display property in CSS. Hiding too much code can be messy and hard to maintain in the future.
Don’t use HTML comments for unused code
This is probably my biggest offender. I’ll sometimes write code and then comment it out if I think that I will use it later. This is a bad habit. If you’re not using the code, delete it. You can always get it back from your version control system.
It makes a difference when you start working on a team and have lots of code commented out. It can be hard to understand why you commented it out and what the purpose of it even is.
How Do HTML Comments impact SEO?
HTML comments can have no impact on SEO. They are not visible to the user, and they are not visible to search engines. So, you can use them freely without worrying about SEO.