微信服务号

微信订阅号

2025-5-13- 5
Home > Archive>Volume 35, Issue 2, 2024 >513-531. DOI:10.13328/j.cnki.jos.006944
PDF HTML XML Export Cite reminder
Survey on Quality of Software Code Comments
Author:
Affiliation:

  • Article
    • | |
  • Metrics
    • |
  • Reference [59]
    • |
  • Related [20]
    • | | |
  • Comments
    Abstract:

    As an essential mechanism of group collaboration in software development, code comments are widely used by developers to improve the efficiency of specific developing tasks. However, code comments do not directly affect the software operation, and developers often ignore them, which leads to poor quality of code comments and affects development efficiency. Quality issues of code comments hinder code understanding, bring misunderstanding, or even introduce bugs, which receive widespread attention from researchers. This study systematically analyzes the research work of global scholars on quality issues of code comments in recent years by literature review. It also summarizes related studies in three aspects: evaluation dimensions of code comment quality, indicators of code comment quality, and strategies to promote code comment quality and points out shortcomings, challenges, and suggestions for the current research.

    Reference
    [1] de Souza SCB, Anquetil N, de Oliveira KM. A study of the documentation essential to software maintenance. In: Proc. of the 23rd Annual Int’l Conf. on Design of Communication: Documenting & Designing for Pervasive Information. Coventry: ACM, 2005. 68-75.
    [2] Arafat O, Riehle D. The comment density of open source software code. In: Proc. of the 31st Int’l Conf. on Software Engineering-companion Volume. Vancouver: IEEE, 2009. 195-198.
    [3] He H. Understanding source code comments at large-scale. In: Proc. of the 27th ACM Joint Meeting on European Software Engineering Conf. and Symp. on the Foundations of Software Engineering. Tallinn: ACM, 2019. 1217-1219.
    [4] Pascarella L, Bacchelli A. Classifying code comments in Java open-source software systems. In: Proc. of the 14th IEEE/ACM Int’l Conf. on Mining Software Repositories (MSR). Buenos Aires: IEEE, 2017. 227-237.
    [5] Aghajani E, Nagy C, Linares-Vásquez M, Moreno L, Bavota G, Lanza M, Shepherd DC. Software documentation: The practitioners’ perspective. In: Proc. of the 42nd IEEE/ACM Int’l Conf. on Software Engineering (ICSE). Seoul: IEEE, 2020. 590-601.
    [6] Nielebock S, Krolikowski D, Krüger J, Leich T, Ortmeier F. Commenting source code: Is it worth it for small programming tasks?. Empirical Software Engineering, 2019, 24(3): 1418-1457. [doi: 10.1007/s10664-018-9664-z]
    [7] Weinberger B, Silverstein C, Eitzmann G, et al. Google C++ style guide. 2013. http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Line_Length
    [8] Ibrahim WM, Bettenburg N, Adams B, Hassan AE. On the relationship between comment update practices and software bugs. The Journal of Systems and Software, 2012, 85(10): 2293-2304. [doi: 10.1016/j.jss.2011.09.019]
    [9] Haouari D, Sahraoui H, Langlais P. How good is your comment? A study of comments in Java programs. In: Proc. of the 2011 Int’l Symp. on Empirical Software Engineering and Measurement. Banff: IEEE, 2011. 137-146.
    [10] Wang C, He H, Pal U, Marinov D, Zhou MH. Suboptimal comments in java projects: From independent comment changes to commenting practices. ACM Transactions on Software Engineering and Methodology, 2022, 32(2): 45. [doi: 10.1145/3546949]
    [11] Goodman LA. Snowball sampling. The Annals of Mathematical Statistics, 1961, 32(1): 148-170.
    [12] Börstler J, Paech B. The role of method chains and comments in software readability and comprehension—An experiment. IEEE Transactions on Software Engineering, 2016, 42(9): 886-898. [doi: 10.1109/TSE.2016.2527791]
    [13] Sukamto RA, Megasari R, Piantari E, Rischa MNF. Code comment assessment development for basic programming subject using online judge. In: Proc. of the 7th Mathematics, Science, and Computer Science Education Int’l Seminar. Bandung: EAI, 2020. 1-5.
    [14] Malik H, Chowdhury I, Tsou HM, Jiang ZM, Hassan AE. Understanding the rationale for updating a function’s comment. In: Proc. of the 2008 IEEE Int’l Conf. on Software Maintenance. Beijing: IEEE, 2008. 167-176.
    [15] Hu X, Xia X, Lo D, Wan ZY, Chen QY, Zimmermann T. Practitioners’ expectations on automated code comment generation. In: Proc. of the 44th Int’l Conf. on Software Engineering. Pittsburgh: ACM, 2022.
    [16] Aghajani E, Nagy C, Vega-Márquez OL, Linares-Vásquez M, Moreno L, Bavota G, Lanza M. Software documentation issues unveiled. In: Proc. of the 41st IEEE/ACM Int’l Conf. on Software Engineering (ICSE). Montreal: IEEE, 2019. 1199-1210.
    [17] Fluri B, Wursch M, Gall HC. Do code and comments co-evolve? On the relation between source code and comment changes. In: Proc. of the 14th Working Conf. on Reverse Engineering (WCRE 2007). Vancouver: IEEE, 2007. 70-79.
    [18] Fluri B, Würsch M, Giger E, Gall HC. Analyzing the co-evolution of comments and source code. Software Quality Journal, 2009, 17(4): 367-394. [doi: 10.1007/s11219-009-9075-x]
    [19] Jiang ZM, Hassan AE. Examining the evolution of code comments in PostgreSQL. In: Proc. of the 2006 Int’l Workshop on Mining Software Repositories. Shanghai: ACM, 2006. 179-180.
    [20] Sun XB, Geng Q, Lo D, Duan YC, Liu XY, Li B. Code comment quality analysis and improvement recommendation: An automated approach. International Journal of Software Engineering and Knowledge Engineering, 2016, 26(6): 981-1000. [doi: 10.1142/S0218194016500339]
    [21] Huang Y, Jia N, Shu JH, Hu XY, Chen XP, Zhou Q. Does your code need comment?. Software: Practice and Experience, 2020, 50(3): 227-245. [doi: 10.1002/spe.2772]
    [22] Huang Y, Hu XY, Jia N, Chen XP, Xiong YF, Zheng ZB. Learning code context information to predict comment locations. IEEE Transactions on Reliability, 2019, 69(1): 88-105. [doi: 10.1109/TR.2019.2931725]
    [23] Louis A, Dash SK, Barr ET, Ernst MD, Sutton C. Where should I comment my code? A dataset and model for predicting locations that need comments. In: Proc. of the 42nd IEEE/ACM Int’l Conf. on Software Engineering: New Ideas and Emerging Results. Seoul: IEEE, 2020. 21-24.
    [24] Wen FC, Nagy C, Bavota G, Lanza M. A large-scale empirical study on code-comment inconsistencies. In: Proc. of the 27th IEEE/ACM Int’l Conf. on Program Comprehension (ICPC). Montreal: IEEE, 2019. 53-64.
    [25] Sondhi D, Gupta A, Purandare S, Rana A, Kaushal D, Purandare R. On indirectly dependent documentation in the context of code evolution: A study. In: Proc. of the 43rd IEEE/ACM Int’l Conf. on Software Engineering (ICSE). Madrid: IEEE, 2021. 1498-1509.
    [26] Rabbi F, Siddik MS. Detecting code comment inconsistency using Siamese recurrent network. In: Proc. of the 28th Int’l Conf. on Program Comprehension. Seoul: ACM, 2020. 371-375.
    [27] Tan SH, Marinov D, Tan L, Leavens GT. @tComment: Testing Javadoc comments to detect comment-code inconsistencies. In: Proc. of the 5th IEEE Int’l Conf. on Software Testing, Verification and Validation. Montreal: IEEE, 2012. 260-269.
    [28] Ratol IK, Robillard MP. Detecting fragile comments. In: Proc. of the 32nd IEEE/ACM Int’l Conf. on Automated Software Engineering (ASE). Urbana: IEEE, 2017. 112-122.
    [29] Lin B, Wang SW, Liu K, Mao XG, Bissyandé TF. Automated comment update: How far are we? In: Proc. of the 29th IEEE/ACM Int’l Conf. on Program Comprehension (ICPC). Madrid: IEEE, 2021. 36-46.
    [30] Liu ZX, Xia X, Yan M, Li SP. Automating just-in-time comment updating. In: Proc. of the 35th IEEE/ACM Int’l Conf. on Automated Software Engineering. Melbourne: IEEE, 2020. 585-597.
    [31] Panthaplackel S, Li JJ, Gligoric M, Mooney RJ. Deep just-in-time inconsistency detection between comments and source code. In: Proc. of the 35th AAAI Conf. on Artificial Intelligence. AAAI Press, 2021. 427-435.
    [32] Nuur A, Gustafsson A, Azimoh A. Analysing the differences in comment quality between open source development and industria practices: A case study. Gothenburg: University of Gothenburg, 2019.
    [33] Jabrayilzade E, Gürkan O, Tüzün E. Towards a taxonomy of inline code comment smells. In: Proc. of the 21st IEEE Int’l Working Conf. on Source Code Analysis and Manipulation (SCAM). Luxembourg: IEEE, 2021. 131-135.
    [34] Steidl D, Hummel B, Juergens E. Quality analysis of source code comments. In: Proc. of the 21st Int’l Conf. on Program Comprehension (ICPC). San Francisco: IEEE, 2013. 83-92.
    [35] Aman H, Amasaki S, Yokogawa T, Kawahara M. A Doc2Vec-based assessment of comments and its application to change-prone method analysis. In: Proc. of the 25th Asia-Pacific Software Engineering Conf. (APSEC). Nara: IEEE, 2018. 643-647.
    [36] Rani P, Panichella S, Leuenberger M, Di Sorbo A, Nierstrasz O. How to identify class comment types? A multi-language approach for class comment classification. Journal of Systems and Software, 2021, 181: 111047. [doi: 10.1016/j.jss.2021.111047]
    [37] Scalabrino S, Linares-Vásquez M, Poshyvanyk D, Oliveto R. Improving code readability models with textual features. In: Proc. of the 24th IEEE Int’l Conf. on Program Comprehension (ICPC). Austin: IEEE, 2016. 1-10.
    [38] Eleyan D, Othman A, Eleyan A. Enhancing software comments readability using flesch reading ease score. Information, 2020, 11(9): 430. [doi: 10.3390/info11090430]
    [39] Ying ATT, Wright JL, Abrams S. Source code that talks: An exploration of Eclipse task comments and their implication to repository mining. ACM SIGSOFT Software Engineering Notes, 2005, 30(4): 1-5. [doi: 10.1145/1083142.1083152]
    [40] Storey MA, Ryall J, Bull RI, Myers D, Singer J. ToDo or to bug. In: Proc. of the 30th ACM/IEEE Int’l Conf. on Software Engineering. Leipzig: IEEE, 2008. 251-260.
    [41] Sridhara G. Automatically detecting the up-to-date status of ToDo comments in Java programs. In: Proc. of the 9th India Software Engineering Conf. Goa: ACM, 2016. 16-25.
    [42] Nie PY, Rai R, Li JJ, Khurshid S, Mooney RJ, Gligoric M. A framework for writing trigger-action todo comments in executable format. In: Proc. of the 27th ACM Joint Meeting on European Software Engineering Conf. and Symp. on the Foundations of Software Engineering. Tallinn: ACM, 2019. 385-396.
    [43] Hata H, Treude C, Kula RG, Ishio T. 9.6 million links in source code comments: Purpose, evolution, and decay. In: Proc. of the 41st IEEE/ACM Int’l Conf. on Software Engineering (ICSE). Montreal: IEEE, 2019. 1211-1221.
    [44] Khamis N, Witte R, Rilling J. Automatic quality assessment of source code comments: The JavadocMiner. In: Proc. of the 15th Int’l Conf. on Application of Natural Language to Information Systems. Cardiff: Springer, 2010. 68-79.
    [45] Tan L, Yuan D, Krishna G, Zhou YY. /*iComment: Bugs or bad comments?*/. In: Proc. of 21st ACM SIGOPS Symp. on Operating Systems Principles. Washington: ACM, 2007. 145-158.
    [46] Rabbi F, Haque MN, Kadir ME, Siddik S, Kabir A. An ensemble approach to detect code comment inconsistencies using topic modeling. In: Proc. of the 32nd Int’l Conf. on Software Engineering and Knowledge Engineering. Pittsburgh: KSI Research Inc., 2020. 392-395.
    [47] Corazza A, Maggio V, Scanniello G. Coherence of comments and method implementations: A dataset and an empirical investigation. Software Quality Journal, 2018, 26(2): 751-777. [doi: 10.1007/s11219-016-9347-1]
    [48] Wang RM, Wang T, Wang HM. Study of a code comment decision method based on structural features. In: Proc. of the 2019 Int’l Conf. on Intelligent Computing, Automation and Systems (ICICAS). Chongqing: IEEE, 2019. 570-574.
    [49] Rani P, Panichella S, Leuenberger M, Ghafari M, Nierstrasz O. What do class comments tell us? An investigation of comment evolution and practices in Pharo Smalltalk. Empirical Software Engineering, 2021, 26(6): 112. [doi: 10.1007/s10664-021-09981-5]
    [50] Linares-Vásquez M, Li BY, Vendome C, Poshyvanyk D. How do developers document database usages in source code? (N). In: Proc. of the 30th IEEE/ACM Int’l Conf. on Automated Software Engineering (ASE). Lincoln: IEEE, 2015. 36-41.
    [51] 黄袁, 贾楠, 周强, 陈湘萍, 熊英飞, 罗笑南. 融合结构与语义特征的代码注释决策支持方法. 软件学报, 2018, 29(8): 2226-2242. http://www.jos.org.cn/1000-9825/5528.htm
    Huang Y, Jia N, Zhou Q, Chen XP, Xiong YF, Luo XN. Method combining structural and semantic features to support code commenting decision. Ruan Jian Xue Bao/Journal of Software, 2018, 29(8): 2226-2242 (in Chinese with English abstract). http://www.jos.org.cn/1000-9825/5528.htm
    [52] Wang DZ, Guo Y, Dong W, Wang ZM, Liu HR, Li SS. Deep code-comment understanding and assessment. IEEE Access, 2019, 7: 174200-174209. [doi: 10.1109/ACCESS.2019.2957424]
    [53] Yang Z, Keung JW, Yu X, Xiao Y, Jin Z, Zhang JY. On the significance of category prediction for code-comment synchronization. ACM Transactions on Software Engineering and Methodology, 2023, 32(2): 30. [doi: 10.1145/3534117]
    [54] Li ZX, Zhong H. Understanding code fragments with issue reports. In: Proc. of the 36th IEEE/ACM Int’l Conf. on Automated Software Engineering (ASE). Melbourne: IEEE, 2021. 1312-1316.
    [55] 郭肇强, 刘释然, 谭婷婷, 李言辉, 陈林, 周毓明, 徐宝文. 自承认技术债的研究: 问题、进展与挑战. 软件学报, 2022, 33(1): 26-54. http://www.jos.org.cn/1000-9825/6292.htm
    Guo ZQ, Liu SR, Tan TT, Li YH, Chen L, Zhou YM, Xu BW. Self-admitted technical debt research: Problem, progress, and challenges. Ruan Jian Xue Bao/Journal of Software, 2022, 33(1): 26-54 (in Chinese with English abstract). http://www.jos.org.cn/1000-9825/6292.htm
    [56] Geng MY, Wang SW, Dong DZ, Gu SZ, Peng F, Ruan WJ, Liao XK. Fine-grained code-comment semantic interaction analysis. In: Proc. of the 30th IEEE/ACM Int’l Conf. on Program Comprehension (ICPC). Pittsburgh: IEEE, 2022. 585-596.
    [57] Liu ZY, Chen HC, Chen XP, Luo XN, Zhou F. Automatic detection of outdated comments during code changes. In: Proc. of the 42nd IEEE Annual Computer Software and Applications Conf. (COMPSAC). Tokyo: IEEE, 2018. 154-163.
    Cited by
    Comments
    Comments
    分享到微博
    Submit
Get Citation

王潮,徐卫伟,周明辉.软件中代码注释质量问题研究综述.软件学报,2024,35(2):513-531

Copy
Share
Article Metrics
  • Abstract:1229
  • PDF: 3894
  • HTML: 2295
  • Cited by: 0
History
  • Received:July 24,2022
  • Revised:December 24,2022
  • Online: August 30,2023
  • Published: February 06,2024
Links:Institute of Software, CASChina Computer FederationCASNSFC
You are the first2044101Visitors
Copyright: Institute of Software, Chinese Academy of Sciences Beijing ICP No. 05046678-4
Address：4# South Fourth Street, Zhong Guan Cun, Beijing 100190,Postal Code：100190
Phone：010-62562563 Fax：010-62562533 Email：jos@iscas.ac.cn
Technical Support：Beijing Qinyun Technology Development Co., Ltd.

Beijing Public Network Security No. 11040202500063