Do you comment your DOM manipulation?

I’m not talking about commenting your code, although you should be doing that anyway. JavaScript has the ability to create HTML comments:

var comment = document.createComment('the comment itself');
document.getElementById('foo').appendChild(comment);

You can even do it in jQuery:

$('<!--the comment itself-->').appendTo('#foo');

Now, I know what you’re thinking: why, why would anyone want to create something that doesn’t appear in the source code and can’t even be seen in Firebug?

Well, it turns out that Firebug is actually unique in it’s decision not to display HTML comments by default. Opera’s Dragonfly, Internet Explorer’s developer tools and the Webkit console all automatically display comments. To see comments in Firebug, click the little arrow next to “HTML” and you’ll be able to see them all.

Since the developer tools are the only places that you can see dynamically created HTML comments, they’re remarkably useful for future developers. Leaving an HTML comment next to any major amount of DOM manipulation can let that future developer know that this is something that’s been dynamically created; if you wanted to be really helpful, you could even put into the comment the name of the function that did the manipulation and a note explaining where to find the documentation. This can be a great way to answer “how did they do that” or sometimes even “why did they do that?”

A couple words or warning if you want to dynamically create HTML comments. First, you can’t put in a double hyphen. Browsers tend to see “--” as the delimiter of a HTML comment, so putting one inside the comment can cause the rest of the comment to become visible. At worst, this can seriously affect the page’s layout.

Another thing to be aware of is that you can’t easily manipulate the comment once it’s been created. In fact, I haven’t managed to find any way of changing a comment at all. If you don’t like the text inside it, you can’t change it. You’d have to insert a new comment just before the old one and then remove the old one.

Finally, if you think you’re likely to change a comment, keep a track of where it is. Store it in a variable, because it’s not as easy to find a HTML comment as it is to find any other element:

document.querySelector('!'); // Throws JavaScript errors.
document.querySelector('!--'); // Also throws JavaScript errors.
document.getElementsByTagName('!--'); // Doesn't work in anything.
document.getElementsByTagName('!'); // Only works in IE.
document.getElementsByTagName('*'); // Only finds comments in IE.

If you need to find comments again, there is some hope. Not the fastest method in the world, but it will work:

// walkTheDOM was written by Douglas Crockford.
function walkTheDOM(node, func) {
    func(node);
    node = node.firstChild;
    while (node) {
        walkTheDOM(node, func);
        node = node.nextSibling;
    }
}

// Starts at the very first possible element and finds all HTML comments.
function findComments() {
    var comments = [];
    walkTheDOM(document.documentElement, function (node) {
        if (node.nodeType === 8) {
            comments.push(node);
        }
    });
    return comments;
}

Leave a Reply

Your email address will not be published. Required fields are marked *