How to Share Code With Users

Published on September 8, 2008 (↻ April 16, 2024), filed under (RSS feed for all categories).

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.

Was this useful or interesting? Share (toot) this post, make a nano-donation, or support my work by learning with my ebooks.

About Me

Jens Oliver Meiert, on September 30, 2021.

I’m Jens (long: Jens Oliver Meiert), and I’m a frontend engineering leader and tech author/publisher. I’ve worked as a technical lead for companies like Google and as an engineering manager for companies like Miro, I’m a contributor to several web standards, 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. (Be critical, interpret charitably, and give feedback.)

Comments (Closed)

  1. 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.

  2. On September 10, 2008, 18:32 CEST, Jens Oliver Meiert said:

    Thank you, Jens… let’s hope that raising these issues has some effect, as taking more responsibility, and be it “just for code,” would go a long way.

  3. 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>