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.