The Complexity of a Simple Code Comment: Genre Conventions, Social Influence, and Rhetorical Functions

Code comments are a common tool used by developers to communicate information about code in software development. These comments are a natural language (e.g., English) comment attached to the line of code that explains the function or purpose of the line and can be used by others on the development team. Thus, these comments, as a rhetorical genre, offer insight into the communication practices and interactions by developers and may create opportunities for better collaboration between developers and technical communicators. This paper reports on the findings of a study that explored how developers write and discuss code comments, including communication with themselves and teammates. Researchers used a survey and a series of interviews to investigate the genre conventions of code comments and how developers use them. Key findings indicate that code comments influence social interactions, that developers have strong opinions about effective comments, and that developers use a peer review process to write and use code comments. These findings reveal overlap with processes and practices used by technical communicators, opening possibilities for shared understandings and stronger collaborations between developers and communicators.