David Patrick Marin

EECS Department, University of California, Berkeley

Technical Report No. UCB/EECS-2005-18

November 23, 2005

http://www2.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.

Advisors: 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://www2.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://www2.eecs.berkeley.edu/Pubs/TechRpts/2005/EECS-2005-18.html
%F Marin:EECS-2005-18