To Document or Not to Document? An Exploratory Study on Developers’ Motivation to Document Code

  • Yulia Shmerlin
  • Irit Hadar
  • Doron Kliger
  • Hayim Makabee
Conference paper
Part of the Lecture Notes in Business Information Processing book series (LNBIP, volume 215)


Technical debt represents the situation in a project where developers accept compromises in one dimension of a system in order to meet urgent demands in other dimensions. These compromises incur a “debt”, on which “interest” has to be paid to maintain the long-term health of the project. One of the elements of technical debt is documentation debt due to under-documentation of the evolving system. In this exploratory study, our goal is to examine the different aspects of developers’ motivation to document code. Specifically, we aim to identify the motivating and hindering aspects of documentation as perceived by the developers. The motivating aspects of code documenting we find include improving code comprehensibility, order, and quality. The hindering aspects include developers’ perception of documenting as a tedious, difficult, and time consuming task that interrupts the coding process. These findings may serve as a basis for developing guidelines toward improving documentation practices and encouraging developers to document their code thus reducing documentation debt.


Documentation Technical debt Motivation 


  1. 1.
    Beecham, S., Baddoo, N., Hall, T., Robinson, H., Sharp, H.: Motivation in software engineering: a systematic literature review. Inf. Softw. Technol. 50(9), 860–878 (2008)CrossRefGoogle Scholar
  2. 2.
    Clear, T.: Documentation and agile methods: striking a balance. ACM SIGCSE Bull. 35(2), 12–13 (2003)CrossRefGoogle Scholar
  3. 3.
    Cunningham, W.: The WyCash portfolio management system. ACM SIGPLAN OOPS Messenger 4(2), 29–30 (1992)MathSciNetCrossRefGoogle Scholar
  4. 4.
    De Souza, S.C.B., Anquetil, N., De Oliveira, K.M.: A study of the documentation essential to software maintenance. In: Proceedings of the 23rd Annual International Conference on Design of Communication: Documenting and Designing for Pervasive Information, pp. 68–75. ACM (2005)Google Scholar
  5. 5.
    Drevik, S.: How to comment code. Embedded Syst. Prog. 9, 58–65 (1996)Google Scholar
  6. 6.
    Fluri, B., Wursch, M., Gall, H.C.: Do code and comments co-evolve? on the relation between source code and comment changes. In: Reverse Engineering 14th Working Conference, pp. 70–79. IEEE (2007)Google Scholar
  7. 7.
    Fogg, B.J.: A behavior model for persuasive design. In: Proceedings of the 4th ACM International Conference on Persuasive Technology (2009)Google Scholar
  8. 8.
    Martin, J., McClure, C.: Software Maintenance: The Problem and the Solutions. Prentice Hall, New York (1983)Google Scholar
  9. 9.
    Seacord, R.C., Plakosh, D.A.: Modernizing Legacy Systems: Software Technologies, Engineering Processes, and Business Practices. Addison-Wesley Professional, Boston (2003)Google Scholar
  10. 10.
    Sharp, H., Baddoo, N., Beecham, S., Hall, T., Robinson, H.: Models of motivation in software engineering. Inf. Softw. Tech 51(1), 219–233 (2009)CrossRefGoogle Scholar
  11. 11.
    Shmerlin, Y., Kliger, D., Makabee, H.: Reducing technical debt: using persuasive technology for encouraging software developers to document Code. In: Iliadis, L., Papazoglou, M., Pohl, K. (eds.) CAiSE Workshops 2014. LNBIP, vol. 178, pp. 207–212. Springer, Heidelberg (2014)Google Scholar
  12. 12.
    Stettina, C.J., Heijstek, W.: Necessary and neglected? An empirical study of internal documentation in agile software development teams. In: Proceedings of the 29th ACM International Conference on Design of Communication, pp. 159–166. ACM (2011)Google Scholar
  13. 13.
    Strauss, A., Corbin, J.M.: Basics of Qualitative Research: Grounded Theory Procedures and Techniques. Sage Publications, London (1990)Google Scholar
  14. 14.
    Tenny, T.: Program readability: procedures versus comments. IEEE Trans. Softw. Eng. 14(9), 1271–1279 (1988)CrossRefGoogle Scholar
  15. 15.
    Tom, E., Aurum, A., Vidgen, R.: An exploration of technical debt. J. Syst. Softw. 86, 1498–1516 (2013)CrossRefGoogle Scholar

Copyright information

© Springer International Publishing Switzerland 2015

Authors and Affiliations

  • Yulia Shmerlin
    • 1
  • Irit Hadar
    • 1
  • Doron Kliger
    • 2
  • Hayim Makabee
    • 3
  1. 1.Information Systems DepartmentUniversity of HaifaHaifaIsrael
  2. 2.Economics DepartmentUniversity of HaifaHaifaIsrael
  3. 3.Yahoo! Research LabsHaifaIsrael

Personalised recommendations