Codelets: Linking Interactive Documentation and Example Code in the Editor

Programmers frequently use instructive code examples found on the Web to overcome cognitive barriers while programming. These examples couple the concrete functionality of code with rich contextual information about how the code works. However, using these examples necessitates understanding, configuring, and integrating the code, all of which typically take place after the example enters the user’s code and has been removed from its original instructive context. In short, a user’s interaction with an example continues well after the code is pasted. This paper investigates whether treating examples as “first-class” objects in the code editor—rather than simply as strings of text—will allow programmers to use examples more effectively. We explore this through the creation and evaluation of Codelets. A Codelet is presented inline with the user’s code, and consists of a block of example code and an interactive helper widget that assists the user in understanding and integrating the example. The Codelet persists through-out the example’s lifecycle, remaining accessible even after configuration and integration is done. A comparative laboratory study with 20 participants found that programmers were able to complete tasks involving examples an average of 43% faster when using Codelets than when using a standard Web browser.