Readability vs Writability

Jay has a great post on readability vs writability.

It's really important to take this into account when performing a usability review on an API. Don't just review the code that a developer has to write in order to accomplish a given task with an API. You should also review the steps that they need to take in order to write that code. In so doing, you might find that even though a particular line of code makes perfect sense when reading code, it might not make so much sense when writing that code.

In one usability study I ran on ADO .Net, participants were asked to write code that queries a table and outputs the results to the console. The results were stored in a DataReader. Many participants expected to find some Count property on the DataReader that they could use to loop through the contents of the datareader, indexing each element in each iteration of the loop. However, no such property existed. Participants spent a significant amount of time looking for other similar properties such as Length, NumberOfRows etc. but did not find anything that would help.

At this point, most participants went to the help docs to find a code sample to help them. As soon as participants found a code sample that showed them that they needed to use an IEnumerator to enumerate through the contents of the DataReader, they understood exactly what they needed to do. Even though the solution was slightly different to the one that participants had orginally attempted, they had no difficulties understanding this new approach.

In other words, the code that participants needed to write to accomplish this task was readable, but not writable. It just wasn't obvious to participants when they originally attempted the task that calling GetEnumerator and using the returned IEnumerator to enumerate the contents of the DataReader was what they needed to do.

In the cognitive dimensions framework, this is covered by the role expressiveness dimension.

Comments

• Anonymous
  July 02, 2004
  The example scared me. Why those participants were not looking for the methods they really need? You should agree that using Count or Legth property is a workaround for the problem of absence of iterator. Why they tried to find the ineffective workaround, while there had been exactly what they needed? Please don't say this approach was new and was not widely known until .NET born!
  Anyhow API author should always remember who will use this API. I think those who use the API have to understand the technology laying at the basement of the API. Else we will rewrite old APIs with new languages and for new platforms. This will cancel out advantages of the languages and platforms.
• Anonymous
  July 06, 2004
  I think you answer your own question Aleksei - API authors should always remember who will use this API. The reason they were not looking for some sort of iterator when they first started working on the task was because they were not used to working with iterators and expected to find something different.
  
  However, note that as soon as they found the code sample showing how to use an IEnumerator to accomplish the task, participants were quite happy with this and were able to accomplish the goal. It's just that using an IEnumerator in this way wasn't what participants were expecting to do to begin with.