Studying Practitioners' Expectations on Clear Code Review Comments

Zhenhao Li,Junkai Chen,Qiheng Mao,Xing Hu,Kui Liu,Xin Xia
2024-10-09
Abstract:The code review comment (CRC) is pivotal in the process of modern code review. It provides reviewers with the opportunity to identify potential bugs, offer constructive feedback, and suggest improvements. Clear and concise code review comments (CRCs) facilitate the communication between developers and is crucial to the correct understanding of the issues identified and proposed solutions. Despite the importance of CRCs' clarity, there is still a lack of guidelines on what constitutes a good clarity and how to evaluate it. In this paper, we conduct a comprehensive study on understanding and evaluating the clarity of CRCs. We first derive a set of attributes related to the clarity of CRCs, namely RIE attributes (i.e., Relevance, Informativeness, and Expression), as well as their corresponding evaluation criteria based on our literature review and survey with practitioners. We then investigate the clarity of CRCs in open-source projects written in nine programming languages and find that a large portion (i.e., 28.8%) of the CRCs lack the clarity in at least one of the attributes. Finally, we propose ClearCRC, an automated framework that evaluates the clarity of CRCs. Experimental results show that ClearCRC can effectively evaluate the clarity of CRCs and outperform the baselines.
Software Engineering
What problem does this paper attempt to address?
The problem that this paper attempts to solve is the clarity of code review comments (CRC). Specifically, the authors note that although CRC is very important in the modern code review process, which can help identify potential errors, provide constructive feedback and suggest improvements, there is currently a lack of specific guidelines on how to define and evaluate CRC clarity. Therefore, the main research objectives of this paper include: 1. **Understanding the attributes of CRC clarity**: Through literature review, initial interviews with industry professionals, and an online questionnaire survey of practitioners, determine the key attributes that affect CRC clarity and develop corresponding evaluation criteria. 2. **Evaluating the clarity of CRC in open - source projects**: Through a manual investigation of CRC in open - source projects of nine programming languages, understand the clarity performance of these comments in practical applications. 3. **Proposing an automated evaluation framework**: Develop an automated framework named ClearCRC for automatically evaluating the clarity of CRC according to the above - mentioned attributes. ### Main research questions - **RQ1: What attributes are related to the clarity of CRC?** - By analyzing the literature review and practitioners' feedback, the authors extract three key attributes: Relevance, Informativeness, and Expression, and develop specific evaluation criteria for each attribute. - **RQ2: How is the clarity of CRC in open - source projects?** - The study finds that approximately 28.8% of CRCs are deficient in at least one attribute, especially in terms of informativeness. - **RQ3: Can the clarity of CRC be automatically evaluated?** - The proposed ClearCRC framework performs well in evaluating CRC clarity, with an average balanced accuracy rate of 77.6%, significantly outperforming the existing baseline methods. ### Contributions of the paper - **Defined the key attributes of CRC clarity and their evaluation criteria**: Through systematic literature review and practitioners' feedback, the three key attributes of CRC clarity and their evaluation criteria are clearly defined. - **Revealed the current situation of CRC clarity in open - source projects**: A large number of CRCs are found to lack sufficient clarity in some aspects. - **Proposed the ClearCRC automated evaluation framework**: This framework can effectively evaluate the clarity of CRC and has better performance than existing methods. In general, this study provides important guidance for understanding and evaluating the clarity of CRC, which is helpful for improving communication efficiency and code quality in the software development process.