Does your code need comment?. (28th November 2019)

• Record Type: Journal Article
• Authors: Huang, Yuan; Jia, Nan; Shu, Junhuai; Hu, Xinyu; Chen, Xiangping; Zhou, Qiang
• Other Names: Bishop Judith guestEditor.; Cooper Kendra M.L. guestEditor.; Sharp Helen guestEditor.; Whalen Michael guestEditor.
• Is Part Of: Software, practice & experience. Volume 50:Number 3(2020)
• Page Start: 227
• Page End: 245
• Publication Date: 2019-11-28
• Subjects: code comment analysis -- commenting necessity -- comment density analysis -- header comment; Computer software -- Periodicals; Computer programming -- Periodicals; Computer programs -- Periodicals; 005.3
• DOI: 10.1002/spe.2772
• Languages: English
• ISSNs: 0038-0644

Abstract

Summary: Code comments convey information about the programmers' intention in a more explicit but less rigorous manner than source code. This information can assist programmers in various tasks, such as code comprehension, reuse, and maintenance. To better understand the properties of the comments existing in the source code, we analyzed more than 450 000 comments across 136 popular open‐source software systems coming different domains. We found that the methods involving header comments and internal comments were shown low percentages in software systems, ie, 4.4% and 10.27%, respectively. As an application of our findings, we propose an automatic approach to determine whether a method needs a header comment, known as commenting necessity identification. Specifically, we identify the important factors for determining the commenting necessity of a method and extract them as structural features, syntactic features, and textual features. Then, by applying machine learning techniques and noise‐handling techniques, we achieve a precision of 88.5% on eight open‐source software from GitHub. The encouraging experimental results demonstrate the feasibility and effectiveness of our approach.