These are lies we tell:

“This is just an example.”

“This is a demo, not for use as production code.”

No, it’s not. You’re wrong. It may not be code you, the author, would use in production. But as soon as you published it, the likelihood that it will become production code in somebody else’s project skyrockets.

And this is inevitably damaging. These examples can be horrible in many ways – reliability, portability, security – and accessibility. In a surprising turn, I’ll be talking about the accessibility problem.

I understand what the problem is – when we write an example, we want it to be a concise demonstration of the principle we’re illustrating, so we strip out the encumbrances like escaping, sanitizing, and elaborations that aren’t central to the point we want to make. Labels and ARIA attributes are definitely in the list of things that make the code more complex.

I don’t have a problem with this.

But when we don’t also include a version of the code that does include everything that makes the code safe and accessible, we act irresponsibly.

Accessibility is a feature that’s far too frequently omitted from examples, unless the examples in question are about accessibility. Fine. Accessibility related attributes are verbose, and may distract from the point in question. But they’re also crucial to the usability of the code for many people. Inviting the propagation of inaccessible code is a shame, and is one of the reasons that the accessibility battle is so difficult.

How about an example?

I’ve seen this many times, but I’m not doing this to call out any particular individuals; this is a systematic problem, and is at its worst in some of the large tutorial oriented sites.

Let’s take a look at an example provided by that stellar example of web programming education, W3 Schools. W3 Schools isn’t exactly known for the highest quality of information — but they are definitely one of the first results you’re likely to find for many basic questions; so this is a place to look to find massively propagated issues.

PHP (Hypertext PreProcessing) 5 Complete Form Example

The tutorial is about how to keep variables in a form after the form is submitted. Obviously, accessibility isn’t the focus of the tutorial. Fair enough.

But knowing people’s habits, what’s going to be taken away from this by a person who’s just trying to learn what to do? This code:


Name: <input type="text" name="name" value="<?php echo 
$name;?>">

E-mail: <input 
type="text" name="email" value="<?php echo $email;?>">


Website: <input type="text" name="website" value="<?php 
echo $website;?>">

Comment: <textarea name="comment" 
rows="5" cols="40"><?php echo $comment;?></textarea>


Gender:
<input type="radio" name="gender"
<?php if (isset($gender) && $gender=="female") echo "checked";?>
value="female">Female
<input type="radio" name="gender"
<?php if 
(isset($gender) && $gender=="male") echo "checked";?>
value="male">Male

This isn’t the full code – so maybe the full, working code example includes some labels. No. No, it doesn’t.

This is an extremely simple form; but every person who copies this into a project because they don’t know any better is creating an inaccessible experience on that project.

What’s your point?

If you’re going to teach somebody about the web, and how to create good products, that means making sure that every example gives the opportunity to do something right — not just a test scenario, to prove that something works in general terms. Education needs to be integrated: it should never be an option to learn how to do something incorrectly. Whatever the specific issue that’s being addressed, the examples used must not simplify to the point that they introduce new problems.