How To Add Comments in Your HTML

Properly commented HTML markup is an important part of a well-built web page. Those comments are easy to add, and anyone having to work on that site's code in the future (including yourself or members of any team you work with) will thank you for those comments.

How to Add HTML Comments

HTML can be authored with a standard text editor, like Notepad++ for Windows or TextEdit for a Ma. You can also use a web design-centric program like Adobe Dreamweaver or even a CMS platform like Wordpress or ExpressionEngine.

Regardless of the tool that you use to author HTML, if you are working directly with the code, you would add HTML comments like this:

  1. Add the first part of the HTML comment tag: <!--
  2. After that opening piece of the comment, write whatever text you would like to appear for this comment. This is likely to be instructions for your or another developer in the future. For example, if you want to designate where a certain section on a page begins or ends in the markup, you could use a comment to detail that.
  3. Once the text of your comment is complete, close the comment tag like this: -->
  4. So in total, your comment will look something like this: <!-- This is where the content of your comment would appear -->

The Display of Comments

Any comments that you add to your HTML code will appear in that code when someone views the source of the web page or opens the HTML in an editor to make some changes. That comment text will not, however, appear in the web browser when a normal visitors come to the site.

Unlike other HTML elements, including paragraphs, headings, or lists, which actually impact the page inside those browsers, comments are really "behind the scenes" pieces of the page.

Comments for Testing Purposes

Because comments do not appear in a web browser, they can be used to "turn off" parts of a page during page testing or development.

If you add the opening part of a comment directly before the part of your page/code that you want to hide, and then you add the closing part at the end of that code (HTML comments can span multiple lines, so you can open a comment on say line 50 of your code and close it on line 75 with no problems), then whatever HTML elements that fall within that comment will no longer be displayed in the browser. They will remain in your code, but will not impact the visual display of the page. If you need to test a page to see if a certain section is causing problems, etc., commenting that area out is preferable to deleting it. With comments, if the section of code in question proves to not be the issue, you can easily remove the comment pieces and that code will be displayed once again. Just be sure that these comments that are used for testing do not make it into production websites. If an area of a page should not be displayed, you want to remove the code, not just comment it out, before you launch that site.

One great use of HTML comments during development is when you are building a responsive website. Because different parts of that site will change their appearance based on different screen sizes, including some areas which may not be displayed at all, using comments to toggle sections of a page on or off can be a quick and easy trick to use during development.

Regarding Performance

I have seen some web professionals suggest that comments should be stripped from HTML and CSS files in order to shave down the size of those files and create faster-loading pages.  While I agree that pages should be optimized for performance and should load quickly, there is still a place for the smart use of comments in code. Remember, these comments are meant to make it easier to work on a site in the future, so as long as you do not overdue it with comments added to every line in your code, the small amount of file size added to a page due to comments should be more than acceptable.

Tips for Using Comments

A few things to be mindful of or remember when using HTML comments:

  1. Comments can be multiple lines.
  2. Use comments to document your page's development.
  3. Comments can al; so document content, table rows or columns, track changes or whatever you would like.
  1. Comments that "turn off" areas of a site should not make it into production unless this change is a temporary one that will be reversed in short order (like having an alert message turned on or off as needed).