How to Comment HTML Code

In HTML documents you can write comments that are not interpreted by the web browser. The purpose of using comments inside your HTML files is to briefly document (explain) the code, either for yourself or for members of your team.

To add a comment in an HTML document, we use the opening and closing comment tags: <!-- --> with text inside, like this:

<!-- Here is a comment on a single line -->

HTML comments can also be on multiple lines:

Here is a comment.
Here is another comment.

Note: when I say that HTML comments are not interpreted by the web browser, I mean that the comments will not be visible to website visitors unless they right-click on the page and click View Page Source. This is also why you should never write sensitive information in your comments, such as passwords.

Is it a good practice to write comments in your HTML code?

It depends on who you ask. Some developers swear against using comments in code files, in general, suggesting that your code should be explicit and self-explanatory. I don’t buy that, because developers have different opinions about what’s explicit and what’s implicit.

I err on the side of making things as obvious as possible. I’d rather explain a little bit too much, than too little. Especially beginners benefit from some extra hand-holding at the beginning of their learning process.

Comments vs Page Load (Performance)

The main downside of comments in your HTML documents is that it does take up some space, which adds more size to your build and thus affects page loading. However, this is only a theoretical problem. Not once have I heard about a website that got a significant performance boost by stripping out comments. Comments take up so little relative space, that it’s a bit ridiculous to stress about.

100 lines of HTML comments take up around 1KB — but that’s without gzipping (a compression method) which would make it significantly less.

Comments should be short and to the point. So unless you’re thinking about writing your next novel inside HTML comments, don’t worry about it.

Instead, you should worry about improving image file compression on your site. Using a better compression method on just a single image on your website is likely to improve your page load more than stripping out 1000s of lines of HTML comments. Just to put things in perspective.

Has this been helpful to you?

You can support my work by sharing this article with others, or perhaps buy me a cup of coffee 😊


Share & Discuss on