Dan's Web Tips | Comments

Dan's Web Tips:

HTML Comments

[<== Previous] | [Up] | [Next ==>]

See also Swedish translation (done by others in their own site)

TIP: When you put comments in your HTML code, begin the comment with <!--, end it with -->, and avoid using -- or > within it.

Many people who attempt to put comments into their HTML code -- text intended for the reference of the developer but not to be displayed by the browser -- get the syntax wrong, which can cause some browsers to mistakenly display part of the comment, or even worse, consider big chunks of the rest of the document to be a comment and ignore them. This widespread confusion about comment syntax is understandable given that HTML comment syntax is a rather inscrutable outgrowth of SGML (Standard Generalized Markup Language), a language devised for the formatting of government documents which formed the basis of HTML. Maybe some of the same people who devised the 1040 tax forms also created the syntax rules for SGML, and hence HTML.

While the popular conception is that comments open with <!-- and end with -->, this isn't quite completely accurate. Actually, comments start and end with "--", as in "-- This is a comment --", but such comments can only occur within the proper SGML context, which happens to be a block starting with <! and ending with >. This ends up producing the commonly observed comment syntax, but it requires the additional condition that you shouldn't have "--" occur in the middle of the comment, because that would mark the end of the comment. Actually, you can use "--" if it's followed with another "--", since multiple comments are allowed. So the following is legal:

<!-- This is a comment -- -- and here's more -->

But since you don't want to have to be so careful in counting your pairs of dashes, it's better not to include any double dashes anywhere in a comment line, so you can be sure the proper syntax is followed. This can get to be a bit of a problem in commenting out JavaScript code (recommended to hide it from older browsers), since "--" is frequently encountered as a decrement operator. You'll have to use your best judgment in such cases about whether to rewrite your JavaScript code to avoid this operator, or live with a malformed "comment" that probably won't crash the common browsers which are used to dealing with such bad syntax anyway. Just try not to use comments like <!--------------> with so many dashes you're likely to lose count.

Another character that you should avoid within comments is the greater-than symbol (>). While this is legal within a comment, some browsers don't parse comments correctly, and they might think that a greater than sign is the end of the comment. So avoid it, though this may pose a problem both in JavaScript code and when you're "commenting out" some HTML markup you're temporarily removing from your page.

Another flawed syntax sometimes used is --!> as the ending sequence of a comment. This is not the correct syntax; no exclamation point is supposed to be at the end of the comment. Technically, the ! sign is here being interposed between the comment's closing "--" and the SGML block-ending ">", and its effect is undefined. Many browsers (perhaps most) will interpret this as the author intended, as the end of a comment, but there may be some that fail to so interpret it, so don't do it this way!

If you use any automated program to generate HTML code, such as a WYSIWYG editor or a program that generates HTML from a spreadsheet or database, watch out for malformed comments these programs may insert; unfortunately, the authors of such software sometimes get the comment syntax wrong and inflict this on all their users.

NOTE: One of the many ways HTML 5.0 "dumbs down" the standards is that it has dropped all attempts to comply with SGML rules, and instead adopts simplified comment syntax rules that don't include many of these complexities; comments are simply delimited by <!-- ... --> as most people mistakenly believed them to be. (In general, the developers of the HTML 5.0 standard seem to have adopted the "If all the idiots mistakenly believe something to be so, then make it so in the new standard!")


  • "Evil Tests" highlight the compliance or noncompliance of your browser with the specs regarding comment syntax.


[<== Previous] | [Up] | [Next ==>]


This page was first created 04 Aug 1997, and was last modified 06 Apr 2002.
Copyright © 1997-2018 by Daniel R. Tobias. All rights reserved.