Towards a rubric proposal for the evaluation of the quality of code comments in Java
DOI:
https://doi.org/10.32870/recibe.v12i1.264Keywords:
Comentario de código, Evaluación, Java, Software, MantenimientoAbstract
In a software development, the documentation plays an important role for knowing the origin, details and reason to be, among other factors of a project. Its utility is wide and is extended even as support for future developers can continue the development with less difficulty. The code of a software is one of the most complex elements to understand, since each developer has their own style of programming. The best way for making the code understandable is accompany it with good comments all of them complete and consistent. In this article, we propose a rubric to evaluate the quality of code comments in Java. This rubric is divided into categories according to the type of comment to be assessed: copyright comment, class comment, method comment, and code snippet comment. Each category defines a set of rules that must be met to declare a comment has quality. Through the increment of readability and maintainability of code in software projects that are currently in use after using the rubric will help us to validate its effectiveness. Once this effectiveness has been verified, it will help the teams to have correctly commented codes and to reduce costs in the work of understanding and maintaining the code, since it will be more readable and descriptive.References
Aman, H., Amasaki, S., Yokogawa, T., & Kawahara, M. (2016). A Doc2Vec-Based Assessment of
Comments and Its Application to Change-Prone Method Analysis. https://bit.ly/2Pb89Au
Bai, Y., Zhang, L., & Zhao, F. (2019). A survey on research of code comment. ACM International
Conference Proceeding Series, 45–51. https://doi.org/10.1145/3312662.3312710
How and When to Deprecate APIs. (n.d.). Retrieved November 22, 2022, from
https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html
How to Write Doc Comments for the Javadoc Tool. (n.d.). Retrieved November 22, 2022, from
https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#tag
Iammarino, M., Aversano, L., Bernardi, M. L., & Cimitile, M. (2019). A Topic Modeling Approach To
Evaluate The Comments Consistency To Source Code. In IEEE Xplore.
Rani, P. (2021). Speculative Analysis for Quality Assessment of Code Comments. Proceedings -
International Conference on Software Engineering, 299–303. https://doi.org/10.1109/ICSECompanion52605.2021.00132
Real Academia Española. (n.d.). Derecho de autor. Retrieved November 7, 2022, from
https://dle.rae.es/derecho#MYrPxAp
Steidl, D., Hummel, B., & Juergens, E. (2013). Quality Analysis of Source Code Comments. In 2013 IEEE
st International Conference on Program Comprehension (pp. 83–92). IEEE.
Wang, D., Guo, Y., Dong, W., Wang, Z., Liu, H., & Li, S. (2019). Deep Code-Comment Understanding
and Assessment. IEEE Access, 7, 174200–174209. https://doi.org/10.1109/ACCESS.2019.2957424
Woodfield, S. N., Dunsrnore, H. E., & Shen, V. Y. (1981). The Effect of Modularization and Comments on
Program Comprehension.
