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.
I agree with the underlying point that code examples should reflect best practice, especially those published for the consumption by others or for teaching.
I am, however, going to pick on the example you’ve chosen. It might be a simplification of examples out on the web. but it contains a useful data-point. Why would someone think it a good idea to teach about input fields without the context of a form.
Maybe that’s where the problem lies, these examples lack an appropriate context. If the context were “this is how to build a form”, then it is inexcusable for a form to then lack labels.
For an example that is just about the input element, I have to question the value of such an example. What is the intention that isn’t better covered by talking about forms as a cohesive whole?
So maybe this is more a contextual problem, and the symptom is example code that isn’t fit for a website build with modern standards and best practice.
I’m totally with you on the first 4 points but I’m curious what you mean/expect for 5 & 6.
If “documenting” is shot gunning comments throughout the code I don’t think this is a good idea as they will be copied and not stripped out… (e.g. fails #4) and is just noise. If separate… my guess is that the blog post the sample is placed in *should* cover that.
For acceptance tests I’m more in the dark… is this a TDD angle? or just a personal checklist before posting?
I agree that the given form/input example is not very good, because it contains non-essential elements, and because it is very incomplete. The br-elements are non-essential, but if the example is only about how to use input elements then I’d argue the text labels themselves are non-essential too.
The example is also incomplete because it only shows two types of input elements, and because it fails to illustrate most of the attributes that are specific to input elements (size, .
Finally, the “text” type appears twice. That duplication is IMO also a matter of non-essential information.
A discussion of how to use label elements to create text prompts would be appropriate if the example is about how to create user-facing forms but not if the example only serves to illustrate the technicalities concerning the input element itself.
IMO insisting that sample code is actually realistic, production – proof code is not realistic since real production code requires a lot of context that only distracts from the matter at hand. It will needlessly complicate learning from the example, since one would either have to explain all the extra code that is not concerned with the matter at hand, or alternatively one would have to explain that all that extra code can be ignored for now. In both cases, it’s a distraction.
Striving to make samples “copy-paste” proof may sound like a good idea, in practice it leads to samples that are complete, self-contained programs themselves. While such a sample may stand on its own feet, it will still be unsuitable to include verbatim into another “real” program.
Hi Isofarro,
There are cases when it appropriate a single element, and this code comes from one of them. There are a lot of attributes and attribute values you can use on a simple
<input>element and an in depth discussion of every aspect of a form could detract from that.However when something is supposed to be “A common form that includes input tags” it’s my view that it should be good quality code, with no excuses such as “it’s only an example”.
Context is important and that’s where documentation comes in. Documentation isn’t just about what every line of code does, it’s also about when, how, and why to use something.
Hi Steve,
Documentation is anything that helps you make sense of the example. This can be comments in the code where necessary, perhaps using JSDoc with JavaScript for example, but it is also explanation of what is significant or important about it. The
<br>h;tags are an example of that. If you are new to web development would you know that beyond putting the following content on a new line that whether it has any significance to the form? Would a<div>be just as good?Acceptance tests are in some ways another way of documenting what is significant, but also demonstrating how to test that you’ve done everything right. Tests don’t have to be automated, but they could be. One of the tests to see if a
<label>is working as expected could be a BDD feature written in Gherkin. Something like:Given a form has an
<input>fieldAnd there is a text associated with the
<input>When I click on the text
Then focus should be set on the
<input>fieldWhat this means is that the person copying the form example can easily see what the expected behaviour is, and can modify the example to fit their specific purpose while retaining the user experience and accessibility benefits.