Empirical Software Engineering

, Volume 17, Issue 6, pp 703–737 | Cite as

What should developers be aware of? An empirical study on the directives of API documentation

  • Martin Monperrus
  • Michael Eichberg
  • Elif Tekes
  • Mira Mezini
Article

Abstract

Application Programming Interfaces (API) are exposed to developers in order to reuse software libraries. API directives are natural-language statements in API documentation that make developers aware of constraints and guidelines related to the usage of an API. This paper presents the design and the results of an empirical study on the directives of API documentation of object-oriented libraries. Its main contribution is to propose and extensively discuss a taxonomy of 23 kinds of API directives.

Supplementary material

10664_2011_9186_MOESM1_ESM.bz2 (2.6 mb)
(BZ2 2.62 MB)
10664_2011_9186_MOESM2_ESM.bz2 (1.2 mb)
(BZ2 1.20 MB)
10664_2011_9186_MOESM3_ESM.bz2 (120 kb)
(BZ2 119 KB)

References

  1. Alexander C, Ishikawa S, Silverstein M (1977) A pattern language: towns, buildings, construction. Oxford University PressGoogle Scholar
  2. Arnout K, Meyer B (2003) Uncovering hidden contracts: the .net example. Comput 36:48–55CrossRefGoogle Scholar
  3. Beckman NE, Kim D, Aldrich J (2011) An empirical study of object protocols in the wild. In: Proceedings of the European conference on object-oriented programming. Springer.Google Scholar
  4. Bierhoff K, Beckman NE, Aldrich J (2009) Practical api protocol checking with access permissions. In: Proceedings of the 23rd European conference on object-oriented programming, Genoa. Springer, Berlin, Heidelberg, pp 195–219Google Scholar
  5. Bloch J (2008) Effective java, 2nd edn. Addisson-WesleyGoogle Scholar
  6. Bokowski B (2008) Java API design. In: Tutorial at the EclipseCon conferenceGoogle Scholar
  7. Bokowski B, Arthorne J, des Rivières J (2006) Designing eclipse APIs. In: Tutorial at the EclipseCon conferenceGoogle Scholar
  8. Bradner S (1997) Key words for use in rfcs to indicate requirement levels. Technical report, IETFGoogle Scholar
  9. Brooks F (1995) The mythical man-month: essays on software engineering. Addison-WesleyGoogle Scholar
  10. Bruch M, Mezini M, Monperrus M (2010) Mining subclassing directives to improve framework reuse. In: Proceedings of the 7th IEEE working conference on mining software repositories. IEEEGoogle Scholar
  11. Clarke S (2004) Measuring API usability. Dr Dobb’s J 29(5):1–5Google Scholar
  12. Cockburn A (2000) Writing effective use cases, 1st edn. Addison-Wesley Longman Publishing Co, IncGoogle Scholar
  13. Dekel U (2009) Increasing awareness of delocalized information to facilitate API usage. PhD thesis, Carnegie Mellon UniversityGoogle Scholar
  14. Dekel U, Herbsleb JD (2009) Improving API documentation usability with knowledge pushing. In: Proceedings of the 31st international conference on software engineering. IEEE Computer Society, pp 320–330Google Scholar
  15. Easterbrook S, Singer J, Storey M-A, Damian D (2007) Selecting empirical methods for software engineering researchGoogle Scholar
  16. Ellis B, Stylos J, Myers B (2007) The factory pattern in api design: a usability evaluation. In: Proceedings of the 29th International Conference on Software Engineering, ICSE ’07. IEEE Computer Society, pp 302–312Google Scholar
  17. Gamma E, Helm R, Johnson RE, Vlissides J (1995) Design patterns: elements of reusable object-oriented software. Addison-WesleyGoogle Scholar
  18. Hovemeyer D, Spacco J, Pugh W (2005) Evaluating and tuning a static analysis to find null pointer bugs. In: Proceedings of the 6th ACM SIGPLAN-SIGSOFT workshop on program analysis for software tools and engineering, PASTE ’05. ACM, New York, NY, USA, pp 13–19CrossRefGoogle Scholar
  19. Jiang ZM, Hassan AE (2006) Examining the evolution of code comments in postgresql. In: Proceedings of the 2006 international workshop on mining software repositories. ACM, pp 179–180Google Scholar
  20. Kramer D (1999) API documentation from source code comments: a case study of javadoc. In: Proceedings of the 17th international conference on computer documentation. ACM, pp 147–153Google Scholar
  21. Monperrus M, Eichberg M, Tekes E, Mezini M (2011) Companion web page for “What should developers be aware of? An empirical study on the directives of API documentation”. http://www.monperrus.net/martin/api-directives. Last accessed: 12 Oct 2011
  22. Nanda MG, Sinha S (2009) Accurate interprocedural null-dereference analysis for java. In: Proceedings of the 31st international conference on software engineering. IEEE Computer Society, pp 133–143Google Scholar
  23. Padioleau Y, Tan L, Zhou Y (2009) Listening to programmers? Taxonomies and characteristics of comments in operating system code. In: Proceedings of the 31st international conference on software engineering. IEEE, pp 331–341Google Scholar
  24. Parnin C, Treude C (2011) Measuring API documentation on the Web. In: Proceeding of the 2nd international workshop on Web 2.0 for software engineering, Web2SE ’11. ACM, pp 25–30Google Scholar
  25. Robillard MP (2009) What makes APIs hard to learn? Answers from developers. IEEE Softw 26(6):27–34CrossRefGoogle Scholar
  26. Shi L, Zhong H, Xie T, Li M (2011) An empirical study on evolution of api documentation. In: Proceedings of the 14th international conference on Fundamental Approaches to Software Engineering, FASE’11/ETAPS’11. Springer, pp 416–431Google Scholar
  27. Singh R, Mangat NS (1996) Elements of survey sampling. SpringerGoogle Scholar
  28. Smith KA, Kramer D (2003) Requirements for writing java API specifications. Technical report, SunGoogle Scholar
  29. Storey MA, Ryall J, Bull RI, Myers D, Singer J (2008) TODO or to bug. In: Proceedings of the ACM/IEEE 30th international conference on software engineering. IEEE, pp 251–260Google Scholar
  30. Stylos J (2009) Making APIs more usable with improved API designs, documentation and tools. PhD thesis, Carnegie Mellon UniversityGoogle Scholar
  31. Stylos J, Myers BA (2008) The implications of method placement on API learnability. In: Proceedings of the 16th ACM SIGSOFT international symposium on foundations of software engineering, SIGSOFT ’08/FSE-16. ACM, New York, NY, USA, pp 105–112CrossRefGoogle Scholar
  32. Stylos J, Graf B, Busse DK, Ziegler C, Ehret R, Karstens J (2008) A case study of api redesign for improved usability. In: IEEE symposium on visual languages and human-centric computing, pp 189–192Google Scholar
  33. Stylos J, Faulring A, Yang Z, Myers BA (2009a) Improving API documentation using API usage information. In: Proceedings of the IEEE symposium on Visual Languages and Human-Centric Computing (VL/HCC’09)Google Scholar
  34. Stylos J, Myers BA, Yang Z (2009b) Jadeite: improving API documentation using usage information. In: Proceedings of the 27th international conference on human factors in computing systems. ACM, pp 4429–4434Google Scholar
  35. Tan L, Yuan D, Krishna G, Zhou Y (2007) icomment: bugs or bad comments. In: Proceedings of the symposium on operating systems principlesGoogle Scholar
  36. Thummalapenta S, Xie T (2008) Spotweb: detecting framework hotspots and coldspots via mining open source code on the Web. In: Proceedings of the international conference on automated software engineering, pp 327–336Google Scholar
  37. Tulach J (2008) Practical API design: confessions of a java framework architect. ApressGoogle Scholar
  38. Watson RB (2009) Improving software API usability through text analysis: a case study. In: Proceedings of the professional communication conference, pp 1–7Google Scholar
  39. Ying ATT, Wright JL, Abrams S (2005) Source code that talks: an exploration of Eclipse task comments and their implication to repository mining. In: Proceedings of mining software repositories. ACM, pp 1–5Google Scholar
  40. Zhong H, Zhang L, Xie T, Mei H (2009) Inferring resource specifications from natural language API documentation. In: Proceedings of the international conference on automated software engineering. IEEE Computer Society, pp 307–318Google Scholar

Copyright information

© Springer Science+Business Media, LLC 2011

Authors and Affiliations

  • Martin Monperrus
    • 1
  • Michael Eichberg
    • 2
  • Elif Tekes
    • 3
  • Mira Mezini
    • 2
  1. 1.ADAM, University of LilleVilleneuve d’Ascq CedexFrance
  2. 2.Software Technology GroupDarmstadt University of TechnologyHochschulstr. 10Germany
  3. 3.PSI Logistics GmBhAschaffenburgGermany

Personalised recommendations