Investigating the Effect of Code Comments on Source Code Comprehension - A Reproduction Study

Abstract

Software comments are written to get an understanding of what code does, its function, and its purpose. There is a consensus in the industry that code comments improve software comprehension, but is this really the case? In this research, we investigate the effect of code comments on software comprehension by conducting an experiment where participants are to study one of three types of code snippets containing the same code. The only difference is the code comments, one contains well-written code comments, one contains poorly-written ones and the last contain no comments at all. Our analysis is done on the data from 51 students studying a programming-related program in Sweden. We split comprehension into two parts, perceived comprehension, which is estimated by the participants after reading the code snippet. And actual comprehension which is tested. Our results show that participants receiving the well-written code comments perceive to comprehend the code snippet better, but in actuality, all three comment types score very similarly on the actual comprehension, with the well-written comments scoring the lowest.