HTMLDoc – a standard for documenting your HTML

usehtmldoc.org

2 points·conwy··2 comments

isnt the purpose of html to be a means of describing information one wishes to convey? At what point is describing the describing of information in order to describe information no longer a self perpetuating loop? I am likely naive or ignorant but isnt there little to no value, as well, to screen readers / alternate html consumers, in terms of accessibility and such? So, i guess my tl:dr is "why?"

edit: thinking deeper into this - this also conflicts with other bastardizations of html comments, used by some apparatuses (gulp initially comes to mind), which need specific, albeit semantically useless, comments as a "hook" (for lack of a better term) to distribute precompiled stuffs and such. Im not endorsing these prior bastardizations any more than I am condemning this idea, rather just pointing out that as well meaning it may have been to contrive this - to me at least, it reads as more shrapnel in a handgrenade.

Thanks for your thoughts.

While I certainly believe in self-documenting code where possible, I think there's a place for comments, and also for well structured comments.

I wouldn't recommend going haywire and commenting on every HTML element, attribute, etc., any more than I'd recommend using any other language facility or tool like a sledgehammer.

But that's not to say structured commenting isn't a useful tool for the right situations. I have found the JSDocs in the code-base of Angular and other libraries to be invaluable, on occasions where it wasn't possible to fully convey the meaning in pure code.

Reply on news.ycombinator.com