A importância de comentar o HTML corretamente

Quando escrevemos HTML em modo padrão, comentários formados incorretamente podem quebrar suas páginas, resultando em parte ou todo o seu conteúdo sendo descomentado. Quando escrevemos XHTML ou XML, comentários incorretos resultarão em seus documentos que não serão capazes de serem exibidos ao todo.

HTML 4.01

De Recomendação W3C HTML 4.01 - Seção 3.2.4 - Comentários:

Espaço em branco não é permitido entre o delimitador aberto de declaração de marcação ("<!") e o delimitador de comentário aberto ("--"), mas é permitido entre o comentário fechado ("--") e o delimitador fechado de declaração de marcação (">"). Um erro comum é incluir uma string de hífens ("---") dentro de um comentário. Autores devem evitar colocar dois ou mais hífens adjacentes dentro de comentários.

Exemplos

O que vem a seguir são comentários válidos em HTML.

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

O que vem a seguir é um comentário não válido em HTML.

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

XML

De Recomendação W3C XML 1.0 - Seção 2.5 - Comentários:

Definições Comentários podem aparecer em qualquer lugar em um documento fora de outra marcação; em adição, eles podem aparecer dentro da declação de tipo de documento em lugares permitidos pela gramática. Eles não são parte dos caracteres de dados do documento; um processo XML pode, mas não precisa, tornar possível para uma aplicação recuperar o texto dos comentários. Por compatibilidade, o string "--" (hífen duplo) não deve ocorrer dentro dos comentários. As referências da entidade do parâmetro não devem ser reconhecidas dentro dos comentários.

[15] Comment ::= '<!--' ((Char - '-') | ('-' (Char - '-')))* '-->'

Como descrito na gramática para comentários em XML, um comentário tem a forma

<!-- characters excluding adjacent dashes -->

Exemplos

O que vem a seguir é um comentário válido em XML e XHTML.

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

O que vem a seguir é um comentário não válido em XML e XHTML.

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

Leitura adicional

• Recomendação HTML 4.01: 3.2.4 - Comentários
• Recomendação XML: 2.5 - Comentários
• Bugzilla bug 144432
• Bugzilla bug 102127