Abstract
In 1997, I worked with a team to conduct my first qualitative research project, a study of how software developers used code libraries when developing a common codebase (McLellan et al. 1998; Spinuzzi 2001). In particular, I was interested in how developers used inline comments to understand their own and others' code. At two sites, the developers used comments pretty much as you might expect: as notes for interpreting and communicating information about the code. But at the third site, developers essentially ignored the comments. One compared the comments to an approaching car's blinker: it might or might not indicate intent, but you'd be foolish to trust it. Another set his editor to gray out comments so they wouldn't distract him. A third used comments - not to interpret the code, but as landmarks for navigating it. "If I have 50 lines of code without a comment," he told me, "I get lost. It takes me a while to actually read the code and find out what it's doing. But if I have comments I can separate it into sections, and if I know it's the second section in the function, I can go right to it."