Netscape DevEdge

Skip to: [content] [navigation]

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.

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.

HTML Examples

The following are valid comments in HTML.

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

The following is not a valid comment in HTML.

<!-- invalid -- html comment -->

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 are not 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 -->

XML 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