How to Share Code with Users
Post from September 8, 2008 (↻ June 12, 2021), filed under Web Development.
This and many other posts are also available as a pretty, well-behaved ebook: On Web Development.
If you share HTML/CSS code with users: Make sure that the code is valid and that ideally, it works in both HTML and XHTML.
Focusing on valid code—a step towards quality code—should be obvious. “Invalidating” other people’s sites isn’t nice. Recommending that code to be insertable without modification in both HTML and supposed XHTML is less evident: It’s often possible to offer the same code for both flavors, and hence such code can improve usability and, ultimately, user experience for the developers embedding your code.
Let’s have a quick look at a made-up code example to demonstrate how all of this can work:
<p>My awesome <a href="https://example.com/?foo=bar&baz=scribble">gadget thingy</a>…<br> Nothing’s better on your site.
Technically valid HTML, except for the classic ampersand issue.
<p>My awesome <a href="https://example.com/?foo=bar&baz=scribble”>gadget thingy</a>…<br> Nothing’s better on your site.
…now fixed. Making this code snippet formally ready for XHTML is simple, too, however, the
br element deserves different treatment in HTML and XHTML. We want elegant code in both. The idea now is to do what web development often asks us to do, to look for alternatives. And, CSS—our partner for all styling questions—to the rescue, we can just replace the
br element by a
<p>My awesome <a href="https://example.com/?foo=bar&baz=scribble">gadget thingy</a>…</p> <p>Nothing’s better on your site.</p>
That should have been easy to follow. Code shared with users is special and means responsibility, and it requires focus on compatibility (different environments, here: document types) and maintainability (the code better be good to spare users from updates and you from supporting legacy code all too soon).
All of this should inspire larger companies, too. The “make sure the HTML is at least valid” part is most important. Don’t hand your users code that that’s of poor quality. Especially if your users have no idea about code.
Update (September 24, 2020)
There’s more! The 4 Pillars of Good Embed Code.
I’m Jens Oliver Meiert, and I’m an engineering manager and author. I’ve worked as a technical lead for Google, I’m close to the W3C and the WHATWG, and I write and review books for O’Reilly. Other than that, I love trying things, sometimes including philosophy, art, and adventure. Here on meiert.com I share some of my views and experiences.
If you have questions or suggestions about what I write, please leave a comment (if available) or a message.
On September 8, 2008, 12:13 CEST, Jens Nedal said:
This certainly works great for templating and i have handled it like this during my career in those cases where we just did the templating and nothing else.
Both HTML and XHTML are equally used and simply have valid code in the first place helps this process alot. The & is one of those nifty little points most people will miss, though you should see it when you validate your pages.
Also providing valid code is simply a must, especially from your professional standpoint. There will always be some customer who actually knows a bit about how designing pages work and some of those who like to nitpick will especially know about ways of finding flaws. So providing templates that validate in either HTML or XHTML is your first step.
Beiing able to provide this for both cases is an absolute plus. Thanks again for worthwhile knowledge and input Jens.
On October 3, 2008, 22:22 CEST, Louis said:
Aren’t you changing the semantic of the code when you split the paragraph in the first snippet into two paragraph in the second snippet?
I mean, in XHTML, aren’t the following two example snippets semanticaly different?
<p>phrase 1<br /> phrase 2</p>
<p>phrase 1</p> <p>phrase 2</p>
Have a look at the most popular posts, possibly including:
Looking for a way to comment? Comments have been disabled, unfortunately.
Perhaps my most comprehensive book: The Web Development Glossary (2020). With explanations and definitions for literally thousands of terms from Web Development and related fields, building on Wikipedia as well as the MDN Web Docs. Available at Apple Books, Kobo, Google Play Books, and Leanpub.