The Importance of Correct Commenting

When authoring HTML in standards mode, incorrectly formed comments can break your pages, resulting in part or all of your content being commented out. When authoring XHTML or XML, incorrect comments will result in your documents not being able to be displayed at all.

HTML 4.01

From W3C HTML 4.01 Recommendation Section 3.2.4 - Comments:

White space is not permitted between the markup declaration open delimiter ("<!") and the comment open delimiter ("--"), but is permitted between the comment close delimiter ("--") and the markup declaration close delimiter (">"). A common error is to include a string of hyphens ("---") within a comment. Authors should avoid putting two or more adjacent hyphens inside comments.

Examples

The following are valid comments in HTML.

<!-- valid html comment -->
<!-- valid html comment -- > 

XML

From the W3C XML 1.0 Recommendation Section 2.5 - Comments:

Definition: Comments may appear anywhere in a document outside other markup; in addition, they may appear within the document type declaration at places allowed by the grammar. They are not part of the document's character data; an XML processor may, but need not, make it possible for an application to retrieve the text of comments. For compatibility, the string "--" (double-hyphen) must not occur within comments. Parameter entity references must not be recognized within comments.
[15] Comment ::= '<!--' ((Char - '-') | ('-' (Char - '-')))* '-->'

As described in the grammar for comments in XML, a comment has the form

<!-- characters excluding adjacent dashes -->

Examples

The following is a valid comment in XML and XHTML.

<!-- valid xml/xhtml comment -->

The following are not valid comments in XML and XHTML.

<!-- invalid -- xml comment -->
<!-- invalid xml comment --->
<!-- invalid xml comment -- >

Further Reading

Original Document Information

  • Last Updated Date: May 19th, 2003
  • Copyright © 2001-2003 Netscape. All rights reserved.

 

Document Tags and Contributors

Last updated by: Dria,