Electrical Engineering
      and Computer Sciences

Electrical Engineering and Computer Sciences

COLLEGE OF ENGINEERING

UC Berkeley

What Motivates Programmers to Comment?

David Patrick Marin

EECS Department
University of California, Berkeley
Technical Report No. UCB/EECS-2005-18
November 23, 2005

http://www.eecs.berkeley.edu/Pubs/TechRpts/2005/EECS-2005-18.pdf

Though programmers are often encouraged to comment their source code more thoroughly, there has been very little scientific investigation into what kinds of situations actually cause programmers to do so. I conducted a statistical study of the CVS repositories of nine Open Source pro jects, and made four major findings. First, the rate at which programmers comment varies widely from pro ject to pro ject and programmer to programmer; even the same programmer will comment at different rates on different pro jects. Second, programmers tend to comment larger modifications to source code more thoroughly. Third, more programmers modifying the same file does not, in general, mean more commenting. Finally, programmers tend to comment more when they are modifying code that is thoroughly commented to begin with. I then determined through an experiment with programmers that there is a causal link behind my last finding; that is, the more throughly a source code file is commented, the more thoroughly programmers will comment when they make modifications to it.

Advisor: Susan L. Graham


BibTeX citation:

@mastersthesis{Marin:EECS-2005-18,
    Author = {Marin, David Patrick},
    Title = {What Motivates Programmers to Comment?},
    School = {EECS Department, University of California, Berkeley},
    Year = {2005},
    Month = {Nov},
    URL = {http://www.eecs.berkeley.edu/Pubs/TechRpts/2005/EECS-2005-18.html},
    Number = {UCB/EECS-2005-18},
    Abstract = {Though programmers are often encouraged to comment their source code more thoroughly, there has been very little scientific investigation into what kinds of situations actually cause programmers to do so. I conducted a statistical study of the CVS repositories of nine Open Source pro jects, and made four major findings. First, the rate at which programmers comment varies widely from pro ject to pro ject and programmer to programmer; even the same programmer will comment at different rates on different pro jects. Second, programmers tend to comment larger modifications to source code more thoroughly. Third, more programmers modifying the same file does not, in general, mean more commenting. Finally, programmers tend to comment more when they are modifying code that is thoroughly commented to begin with. I then determined through an experiment with programmers that there is a causal link behind my last finding; that is, the more throughly a source code file is commented, the more thoroughly programmers will comment when they make modifications to it.}
}

EndNote citation:

%0 Thesis
%A Marin, David Patrick
%T What Motivates Programmers to Comment?
%I EECS Department, University of California, Berkeley
%D 2005
%8 November 23
%@ UCB/EECS-2005-18
%U http://www.eecs.berkeley.edu/Pubs/TechRpts/2005/EECS-2005-18.html
%F Marin:EECS-2005-18