The implications of method placement on API learnability

ABSTRACT

To better understand what makes Application Programming Interfaces (APIs) hard to use and how to improve them, recent research has begun studying programmers' strategies and use of APIs. It was found that method placement --- on which class or classes a method is placed --- can have large usability impact in object-oriented APIs. This was because programmers often start their exploration of an API from one "main" object, and were slower finding other objects that were not referenced in the methods of the main object. For example, while mailServer.send(mailMessage) might make sense, if programmers often begin their API explorations from the MailMessage class, then this makes it harder to find the MailServer class than the alternative mailMessage.send(mailServer). This is interesting because many real APIs place methods essential to common objects on other, helper objects. Alternate versions of three different APIs were compared, and it was found that programmers gravitated toward the same starting classes and were dramatically faster --- between 2 to 11 times --- combining multiple objects when a method on the starting class referred to the other class.

REFERENCES

• 1: Joshua Bloch, Effective Java programming language guide, Sun Microsystems, Inc., Mountain View, CA, 2001
• 2: Bore, C., and S. Bore, "Profiling software API usability for consumer electronics", Consumer Electronics, 2005.
• 3: Craig Chambers, Object-Oriented Multi-Methods in Cecil, Proceedings of the European Conference on Object-Oriented Programming, p.33-56, June 29-July 03, 1992
• 4: Clarke, S. Measuring API Usability. Dr. Dobbs Journal, May 2004, pp S6--S9. 2004.
• 5: Clarke, S. Describing and Measuring API Usability with the Cognitive Dimensions. Cognitive Dimensions of Notations 10^th Anniversary Workshop. 2006.
• 6: Clarke, S. "What is an End User Software Engineer?", End User Software Engineering, Dagstuhl Seminar Proceedings, Dagstuhl, Germany, 2007.
• 7: Cwalina, K. and Abrams, B. Framework Design Guidelines. Addison-Wesley, Upper Saddle River, NJ, 2005.
• 8: Robert DeLine , Mary Czerwinski , George Robertson, Easing Program Comprehension by Sharing Navigation Data, Proceedings of the 2005 IEEE Symposium on Visual Languages and Human-Centric Computing, p.241-248, September 20-24, 2005 [doi>10.1109/VLHCC.2005.32]
• 9: Brian Ellis , Jeffrey Stylos , Brad Myers, The Factory Pattern in API Design: A Usability Evaluation, Proceedings of the 29th international conference on Software Engineering, p.302-312, May 20-26, 2007 [doi>10.1109/ICSE.2007.85]
• 10: Green, T. R. G., and M. Petre, "Usability Analysis of Visual Programming Environments: A 'Cognitive Dimensions' Framework", Journal of Visual Languages and Computing, 1996, pp 131--174.
• 11: Reid Holmes , Gail C. Murphy, Using structural context to recommend source code examples, Proceedings of the 27th international conference on Software engineering, May 15-21, 2005, St. Louis, MO, USA [doi>10.1145/1062455.1062491]
• 12: Andrew J. Ko , Brad A. Myers , Htet Htet Aung, Six Learning Barriers in End-User Programming Systems, Proceedings of the 2004 IEEE Symposium on Visual Languages - Human Centric Computing, p.199-206, September 26-29, 2004 [doi>10.1109/VLHCC.2004.47]
• 13: Thomas D. LaToza , David Garlan , James D. Herbsleb , Brad A. Myers, Program comprehension as fact finding, Proceedings of the the 6th joint meeting of the European software engineering conference and the ACM SIGSOFT symposium on The foundations of software engineering, September 03-07, 2007, Dubrovnik, Croatia [doi>10.1145/1287624.1287675]
• 14: Joseph Lawrance , Rachel Bellamy , Margaret Burnett, Scents in Programs: Does Information Foraging Theory Apply to Program Maintenance?, Proceedings of the IEEE Symposium on Visual Languages and Human-Centric Computing, p.15-22, September 23-27, 2007 [doi>10.1109/VLHCC.2007.48]
• 15: Samuel G. McLellan , Alvin W. Roesler , Joseph T. Tempest , Clay I. Spinuzzi, Building More Usable APIs, IEEE Software, v.15 n.3, p.78-86, May 1998 [doi>10.1109/52.676963]
• 16: Stephens, D. W., and Krebs, J. R. Foraging theory. Princeton, NJ: Princeton University Press. 1986
• 17: Jeffrey Stylos , Brad A. Myers, Mica: A Web-Search Tool for Finding API Components and Examples, Proceedings of the Visual Languages and Human-Centric Computing, p.195-202, September 04-08, 2006 [doi>10.1109/VLHCC.2006.32]
• 18: Jeffrey Stylos , Steven Clarke, Usability Implications of Requiring Parameters in Objects' Constructors, Proceedings of the 29th international conference on Software Engineering, p.529-539, May 20-26, 2007 [doi>10.1109/ICSE.2007.92]
• 19: Jeffrey Stylos , Brad Myers, Mapping the Space of API Design Decisions, Proceedings of the IEEE Symposium on Visual Languages and Human-Centric Computing, p.50-60, September 23-27, 2007 [doi>10.1109/VLHCC.2007.36]

INDEX TERMS

Primary Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
        D.2.13 Reusable Software
            Subjects: Reusable libraries

Additional Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
        D.2.11 Software Architectures
            Subjects: Patterns (e.g., client/server, pipeline, blackboard)

General Terms:
Design, Experimentation, Human Factors

Keywords:
APIs, documentation, frameworks, libraries, usability, user studies