Comments on Comments

What are HTML Comments and How are they Used

HTML code
zokara/E+/Getty Images

 

aWhen you view a webpage in a browser, you are seeing a visual representation of what that piece of software (the web browser) is displaying based on the code of a particular webpage. If you view that source code of the webpage, you will see a document made up of various HTML elements, including paragraphs, headings, lists, links, images and more. All of these elements are rendered by the browser on a visitor's screen as part of the display of the website.

One thing you may find in HTML code that is not rendered on a person's screen are what are known as "HTML comments".

What Is a Comment?

A comment is a string of code within HTML, XML, or CSS that is not viewed or acted upon by the browser or parser. It is simply written into the code to provide information about that code or other feedback from the code developers.

Most programming languages have comments, they are commonly used by the code's developer for one or even more than one, of the following reason:

  • Describe and explain complicated code to someone who may have to work on it in the future - including themselves! They may come back to code 3 or 6 of 12 months or more later and not remember why they did something a certain way. Comments can help answer their questions and remind them of where their mind was when they were first developing that page.
  • Provide details about when the code was edited or reviewed. This can be helpful information and act somewhat like a development log of when a site was last worked on.
  • Remove sections of the code, but leave them available for later use. This is often done during site testing and debugging. If you have a problem on a site and are not sure what is causing it, you can comment out sections one at a time to quarentine and identify the issue, and then work on a fix for whatever problems you are having.
  • Chat with other developers working on the code. This would likely be done during development as a way to share details with others working on the code at the same time. If these comments are purely development conversations, it is a best practice to remove them from the code before a site is launched.

Traditionally, comments in HTML are used for nearly any elements, from explanations of complex table structures to informative remarks of the content of the page itself. Since comments are not rendered in a browser, you can add them anywhere in the HTML and have no worries of what it will do when the site is viewed by a customer.

How to Write Comments

Writing comments in HTML, XHTML, and XML is very easy. Simply surround the text you want commented out with the following:

<!--

and

-->

As you can see, these comments begin with a "less than symbol", plus an exclaimation point and two dashes.  The comment ends with two more dashes and a "greater than: symbol. Between those characters  you can write whatever you want to make up the body of the comment.

In CSS, it's a little different, using C code comments rather than HTML You begin with a forward slash followed by an asterisk. You end the comment with the inverse of that, an asterisk followed by a forward slash.

/* commented text */

Comments are a Dying Art

Most programmers know the value of useful comments. Commented code makes it easier for that code to be transferred from one team member to another. Comments help you QA team to test the code, because they can tell what the developer intended - even if it wasn't achieved. Unfortunately, with the popularity of website authoring platforms like Wordpress, which allow you to get up and running with a chosen theme that handles much, if not all, of the HTML for you, comments are not used as often by web teams. This is because the comments are really hard to see in most visual authoring tools if you are not working directly with the code. For example, rather than seeing, at the top of a webpage:

<!-- DO NOT EDIT THIS PAGE, IT'S AUTO-GENERATED BY A SCRIPT -->

The visual tool shows a tiny icon to indicate that a comment is there. If the designer doesn't physically open the comment, he may never see it. And in the case of the above page, could cause problems if she edits the page and that editing is over-written by the script mentioned in the comment.​

What Can Be Done?

  1. Write meaningful and useful comments. Don't expect other people to read your comments if they are too long or don't include helpful information.
  2. As a developer, you should always review any comments you see on a page.
  3. Use tools provided by the authoring programs that allow you to add comments.
  4. Use content management to control how the pages are edited.

Even if you're the only person who edits your webpages, comments can be useful. If you only edit a complicated page once a year, it's easy to forget how you built the table or put together the CSS. With comments, you don't have to remember, as it's written right there for you.

Original article by Jennifer Krynin. Edited by Jeremy Girard on 5/5/17