All of us who build websites or application have at one time or another copied example or demo code and used it in our own work. Heck, a large number of us learnt our craft this way.
Unfortunately the quality of example code, while varying widely, is often on the poor side. This is not because the well meaning developers who publish it are bad developers, but because they aim to keep things simple and just show the bare minimum.
The problem with this is that by avoiding the complete picture the wrong lessons are learnt.
Take the following, which is an example how to use the
<input> element from a popular (and generally excellent) website:
<!-- A common form that includes input tags --> <form action="getform.php" method="get"> First name: <input type="text" name="first_name" /><br /> Last name: <input type="text" name="last_name" /><br /> E-mail: <input type="email" name="user_email" /><br /> <input type="submit" value="Submit" /> </form>
While this does indeed show a simple way of using
<input> elements, by not wrapping the text adjacent to each field in a
<label> element it is an example that suffers from a serious but easy to avoid accessibility flaw.
The usual excuse is “It’s only meant to be an example”, but my guess is that this code has been copied and pasted in to many live websites, and has therefore failed in its purpose to educate on the correct way to implement a form.
I think there is only one way to solve this, and it’s going to take a bit of work:
Example and demo code must be of production quality
Whenever we provide example code or demo implementations it must be good enough that we would be prepared to use it exactly as it is in our own production work. We must assume that every example will be used verbatim, without improvement.
The checklist that I assess my work against looks something like this:
- has been well tested
- is secure
- is accessible
- is performant
- is documented
- has acceptance tests
Hopefully the first 4 points go without saying, but why would you include documentation or tests in a demo? Well, first of all they are part of what I consider a necessary part of production quality code, but more importantly they are a way of educating the person who copies it.
Both documentation and tests provide ways of indicating what is significant rather than unimportant. In the previous shown code, is it significant to the quality of the implementation that each input is separated by
<br />? I’m sure we’d agree not, indeed it’s not how I’d implement this. But documentation that spells out that
<label> elements should be used, along with acceptance tests that make sure that they have been, means that when an example is adapted to meet a new requirement it retains its quality.
Education via example is how the web has become the amazing platform it is today. Let us all do our best to improve the lessons we teach.