Structuring Documentation to Support State Search: A Laboratory Experiment about Protocol Programming
Structuring Documentation to Support State Search: A Laboratory Experiment about Protocol Programming
复制标题
DOI：
10.1007/978-3-662-44202-9_7
复制
发表时间：
2014-08
期刊：
影响因子：
--
通讯作者：
Joshua Sunshine;J. Herbsleb;Jonathan Aldrich
中科院分区：
文献类型：
--
作者：
Joshua Sunshine;J. Herbsleb;Jonathan Aldrich
应用程序编程接口（API）通常定义对象协议。具有协议的对象具有有限数量的状态，并且在每个状态中，不同的方法调用集是有效的。许多研究人员已经开发了协议验证工具，因为协议是出了名的难以正确遵循。然而，最近的研究表明，API协议程序员的一个主要挑战是有效地搜索状态空间。核查是这种搜索的无效指南。在本文中，我们提出了Plaiddoc，它类似于Javadoc，除了它通过状态而不是类来组织方法，它包括显式的状态转换，基于状态的类型规范和丰富的状态关系。我们比较Plaiddoc的Javadoc控制在一个受试者之间的实验室实验。我们发现，Plaiddoc参与者完成状态搜索任务的时间显着更少，错误显着减少比Javadoc参与者。
Application Programming Interfaces (APIs) often define object protocols. Objects with protocols have a finite number of states and in each state a different set of method calls is valid. Many researchers have developed protocol verification tools because protocols are notoriously difficult to follow correctly. However, recent research suggests that a major challenge for API protocol programmers is effectively searching the state space. Verification is an ineffective guide for this kind of search. In this paper we instead propose Plaiddoc, which is like Javadoc except it organizes methods by state instead of by class and it includes explicit state transitions, state-based type specifications, and rich state relationships. We compare Plaiddoc to a Javadoc control in a between-subjects laboratory experiment. We find that Plaiddoc participants complete state search tasks in significantly less time and with significantly fewer errors than Javadoc participants.