Automated Analysis of Commenting Styles and Documentation Practices: A Data-Driven Approach to Software Quality and Maintainability

Abstract

Software maintainability is strongly influenced by the quality of code comments, which guide developers in understanding system functionality and behaviour. Poorly written, missing, or ambiguous comments reduce productivity and increase the cost of maintenance. The current study introduces an automated, data-driven approach to evaluating comment quality in Java projects. The proposed solution, implemented as a Java-based tool named Comment Quality Analyser, automatically scans source files, extracts comments, and evaluates them using four quality dimensions: grammatical correctness, readability, understandability, and meaningfulness. The tool integrates LanguageTool for grammatical analysis, the Flesch Reading Ease metric for readability, heuristic rules for understandability, and a Jaccard-similarity-based algorithm for measuring semantic alignment between comments and code identifiers. The results are presented through JSON reports and an interactive HTML dashboard that visualises the quality distribution across files. Real-world validation was conducted using the Apache Commons IO open-source repository, containing over 100 comments. Experimental results indicate that the system provides consistent scoring with an average accuracy of 86 % when compared with manual reviews. The proposed framework contributes to improving software documentation practices and offers a foundation for further research integrating Natural Language Processing (NLP) and Machine Learning (ML) to enhance software maintainability analysis.