Why you should care
Commented code lines rate is the percentage of lines of codes that are preceded with at least one line of comment. Comments are essential in every programming language for summarizing, communicating and clarifying sections of code – in order to assist others working on an application.
Low commented code lines can cause readability and collaboration issues among developers, which increases development time and effort. When done properly, commenting can help maintain code expansions and help find bugs faster.
A low rate of commenting within an application increases the difficulty that different developers and different teams face when writing new code, since it takes more effort to interpret and modify existing code (this includes external clients who might need to interact directly with an API or otherwise). It also hurts development speed since comments also serve to guide the debugging process.
CAST recommends establishing an internal standard for code commenting. Ensuring that each application and their corresponding development team has a unified style guide, in order to standardize the type and commonality of comments.
Developers and project leaders should think about what portions of their codebase may require effort to understand and make appropriate, meaningful additions. Nonetheless, they should avoid superfluous additions to sections that are self-explanatory. And finally there should be an emphasis on writing comments alongside the development process, rather than after the fact.
How we detect
(Nbr_CommentsBlocs / Nbr_LinesOfCode) * 100
The total number of lines containing code items (syntax, string).
Blank lines, comments and docstring are excluded
Total number of comment blocs.
A Comment bloc is a set of contiguous lines containing comment, or docstring, and no code items.
Inlines comments count as a bloc.
About CAST and Highlight’s Code Insights
Over the last 25 years, CAST has leveraged unique knowledge on software quality measurement by analyzing thousands of applications and billions of lines of code. Based on this experience and community standards on programming best practices, Highlight implements hundreds of code insights across 15+ technologies to calculate health factors of a software.