Should I mark what blocks mean in data-* attributes?

Question

I was writing a webpage today with a comment after the start of every major section. Instead of using a comment, which comes with the bulgy <!-- --> syntax, could I instead put this in a data-* attribute? This would be more for me than anything else, so I don't want to put it in an id or class, but it would also leave it open for userscripts to more easily parse the page.

Examples

My current method:

<article> <!-- news -->
    <header> <!-- headline -->
        <h1>How To Fix Everything</h1>
    </header>

    <section> <!-- news body -->
        <p>This is the best magic there is:</p>
        <ol>
            <li>Find a problem</li>
            <li>FIX IT</li>
            <li>Back to step 1</li>
        </ol>
    </section>

    <footer> <!-- social -->
        <a href="//example.com/share">Share on Example.com!</a>
    </footer>
</article>

My proposed method:

<article data-news>
    <header data-headline>
        <h1>How To Fix Everything</h1>
    </header>

    <section data-news-body>
        <p>This is the best magic there is:</p>
        <ol>
            <li>Find a problem</li>
            <li>FIX IT</li>
            <li>Back to step 1</li>
        </ol>
    </section>

    <footer data-social>
        <a href="//example.com/share">Share on Example.com!</a>
    </footer>
</article>

Answer 1

Use a class.

A class labels the contents on it if you work semantically. That you can use a CSS selector on it is, of course, also good and useful, but in general it describes the role of the element, and that's exactly what you are looking for.

Next to that, people are used to reading class names as semantic data describing the element.

It also reduces duplicate code because you would use a class also for the CSS anyway. Even if you don't need the class in CSS at this moment, it can be good to attach it. That said, it has a real meaning. That will make it possible to change the styles easier without changing classes in the HTML, which is important in bigger teams.

And finally, it makes code more readable in general, because you can simply match the class. That seems (but that's never stable) to be, performance-wise, a good solution. In terms of code organisation, it makes things much easier to deal with.

Answer 2

The current HTML5 spec (PR) says about custom data attributes (emphasis mine):

Custom data attributes are intended to store custom data private to the page or application, for which there are no more appropriate attributes or elements.

And the definition of the class attribute contains:

[…] representing the various classes that the element belongs to […]

[…] authors are encouraged to use values that describe the nature of the content […]

So it seems that class is more appropriate than data-* for your use case.

However, it would not be wrong to use custom data attributes instead (or in addition). It’s your understanding of your content that matters, and you might argue that something is or is not a class (as only vaguely defined by the spec).

(CSS doesn’t matter for this decision at all, as you can use both attributes as hooks in your CSS.)

(Side note: Your use of section in this example is most likely wrong. Don’t use it for the "text body" of an article. Only use section here if it represents a sub-section of the parent section, i.e., when you are using sub-headings.)

Answer 3

I would use classes as what your doing is adding contextual classification:

<footer class="social">
  <a href="//example.com/share">Share on Example.com!</a>
</footer>

Can be read as its a footer containing social media functions, which has a more specific semantical meaning than just <header>.

This together with role attributes can be used to make html better describe subject matter.