Ensure the code contains enough block of comments
This code insight verifies the ratio between the number of comment blocks and total lines of code instructions (comment, blank and docstring excluded). Depending on the calculated ratio and the technology (by design, some programming languages – keywords, operators, etc. – require less comments to be understood while other may look more obscure), Highlight counts penalty points for the scanned file. For instance, a low ratio indicates the source code has not enough comment blocks compared to the source volume being scanned, while a higher ratio indicates the source code contains a well-balanced number of comment blocks.
Why you should care
On average, a developer can write approximately 10 lines of code per day. The rest of the time he/she is trying to understand the existing code (and probably attends boring meeting too). That’s even more true when the application is a) not very recent; b) complex and; c) outsourced. Adding a comment that explains how a piece of code is supposed to work is a great help for development teams. A well-documented application generally means lower maintenance cost and tends to be less error-proned when modifications need to be made in the software.
CAST recommendations
If this code insight regularly shows up in your software, you may want to tell your development team to ensure the application is regularly enriched with useful textual comments to quickly understand the logic behind the code.
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.