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

Code comments are a common tool developers and engineers use to communicate information about their coding project. Researchers define code comments as a natural language (e.g. English) comment attached to a line of code that explains the function and/or purpose of the line. This study explored how developers and engineers write and discuss code comments, including communication with themselves and teammates. The study investigated the genre conventions of code comments, and how developers and engineers use them beyond the above definition (e.g. personal commenting, emotional outbursts, other “types” of comments). Key findings indicate that because code comments do not have specific genre conventions, they can heavily influence social interactions between teammates. Developers and engineers have strong opinions about how to write code comments, and their opinions shape how they view teammates’ comments and general communication. Participants also shared how they use a peer review process similar to the writing process: they often look at each others’ work, provide feedback, and brainstorm ideas. These shared practices can be used by technical communicators to relate to developers and engineers when writing is involved.