[Or, When Minutiae Attack!]

There's a perennial question that pops up on email lists and from other developers. The question goes something like this:

"This page works fine in everything except Firefox and I can't tell why... it's showing an HTML comment as raw code..."

the problem

This problem usually boils down to a quirk in the way Firefox handles HTML comments. Most browsers only treat --> as a closing comment in HTML. However, Firefox also treats any instance of -- as a closing comment.

So, if you have a comment with two or more adjacent hyphens, you're in trouble. Both of these are out:

<!-- --------------- Blah --------------- -->

Blah blah blah -- then blah.</p>

Firefox will display the comment as raw code, instead of hiding the comment and its contents. The late Netscape Navigator did this too - in fact I first saw the problem in NN4, back in 2000.

the solution

The solution is simple, even if it's not always convenient: don't put adjacent hyphens inside an HTML comment. That's fine and dandy unless you have content authors who have a habit of using two hyphens instead of an em dash!

In any case, you either need to remove the adjacent hyphens, or if it's appropriate you can convert them to more correct characters.

If your page's content includes double hyphens and you're not allowed to modify it, then you're not going to be able to comment blocks of it out. Yes, that is indeed annoying.

is firefox wrong?

Technically, very technically, Firefox is right. The HTML 4 specification defines "--" as the comment delimiters; while "<!" and ">" are the markup declaration delimiters. From the spec:

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.

Information that appears between comments has no special meaning (e.g., character references are not interpreted as such).

Note that comments are markup.

...so, Firefox is not "wrong". It's just following the spec to the letter (or hyphen, as the case may be). The other browsers have gone with a more human-friendly interpretation of the spec.

so are all the other browsers wrong?

I don't think the other browsers are definitively wrong either. They still comply with a different interpretation. Personally I read the specification the same way: "any instance of -- followed by > or whitespace and > is a closing comment".

According to this interpretation, "-->" and "--  >" are valid closing comments, but "-- blah" is not. It's also a reasonably logical approach to say that since a closing comment should be "-->", then the browser should ignore anything which is not "-->". That's pretty much what a comment is there for, after all - to ignore stuff.

is the spec wrong?

Well the spec can't really be "wrong" I guess. It is what it is. But in this case I think the specification is a bit illogical:

  • I don't see the sense in random exceptions to rules - why specify vagueness? "this is the closing comment tag, except when it's not".
  • Why allow whitespace in the closing comment, when it's not allowed in the opening comment? If whitespace was prohibited the only valid interpretation would have been the complete "-->" and the whole problem goes away.
  • The "common error" note just confuses the issue. It does not say why including adjacent hyphens is an error, nor does it define any specific error handling method.
  • The double-hyphen approach can't be a technical requirement for producing a rendering engine, since the other browsers are able to restrict closing comments specifically to "-->".
  • It's impractical to expect that commented content will never contain multiple adjacent hyphens. Sure, we can live without hyphens in comments; but we shouldn't dictate content based on markup (no matter how small a detail it is).
  • And finally... it's irritating, so I'm going to be cranky at the spec ;)

Besides that, as the HTML5 spec notes, HTML has always been implemented by browsers as a language in its own right. There's no need to slavishly follow anything else. The more human interpretation could just as easily have been specified.

But then, comments appear to be a blind spot in W3C specs - how I curse the lack of a single-line comment in CSS... but I digress.

will html5 clear it up?

No. HTML5 actually makes things a little harder to remember, by addingdocumenting (hat tip zcorpan) the restriction that a comment can't end with a hyphen either:

Comments must start with the four character sequence U+003C LESS-THAN SIGN, U+0021 EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS (<!--). Following this sequence, the comment may have text, with the additional restriction that the text must not contain two consecutive U+002D HYPHEN-MINUS (-) characters, nor end with a U+002D HYPHEN-MINUS (-) character. Finally, the comment must be ended by the three character sequence U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN (-->).

What's the saying about laws and sausages?


Perhaps there's some deep-seated syntactical reason for the double hyphen approach. The HTML4 spec's warning about "a common error" hints at some underlying logic without actually revealing it. Maybe it's related to the formatting of DTD comments. Maybe it was just a Netscape quirk which got turned into a standard. Maybe it's totally random.

It seems unlikely that Mozilla is going to change this particular detail, particularly as it's not a "bug" to follow the specifications; and besides, Firefox 3 Beta 2 still has the quirk.

Still, Firefox does correct omitted background colours by defaulting to white - so they're not above "helpful" rendering tricks. So maybe there's some hope on that front.

But in the meantime, no matter what we think we just have to live with it. It's yet another bit of web development minutiae to file away in your head, for the day you see it happen.

Update 2011.10.17: a quick test in Firefox 6 and 7 suggests they've finally fixed this issue. With the suggestion that FF 3.6 will reach EOL in the near future, we might finally be able to say goodbye to this curious little problem.