How to Share Code With Users

Published on Sep 8, 2008 (updated Apr 16, 2024), filed under development, quality (feed). (Share this on Mastodon or Bluesky?)

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 with 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 code to be insertable without modification with 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, the experience of 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 for your site.

Technically valid HTML, except for the classic ampersand issue:

<p>My awesome <a href="https://example.com/?foo=bar&amp;baz=scribble”>gadget thingy</a>…<br>
Nothing’s better for your site.

…now fixed. [In Chapter 2 of Upgrade Your HTML, I’ll argue not to escape ampersands unless necessary, but that happens many years later, in a different world of web development.]

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 replace the br element by a p element:

<p>My awesome <a href="https://example.com/?foo=bar&amp;baz=scribble">gadget thingy</a>…</p>
<p>Nothing’s better for your site.</p>

That should have been easy to follow. Code shared with users comes with 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 badly aging code).

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 don’t have a good idea about code.

Update (September 24, 2020)

There’s more! The 4 Pillars of Good Embed Code.

About Me

I’m Jens (long: Jens Oliver Meiert), and I’m a web developer, manager, and author. I’ve been working as a technical lead and engineering manager for small and large enterprises, I’m an occasional contributor to web standards (like HTML, CSS, WCAG), and I write and review books for O’Reilly and Frontend Dogma.

I love trying things, not only in web development and engineering management, but also in other areas like philosophy. Here on meiert.com I share some of my experiences and views. (I value you being critical, interpreting charitably, and giving feedback.)