Remembering Comment Ratio

Back in my college days, I had studied the "comment ratio" metric in my Software Engineering class. It was still in use when I joined the industry, though nobody on my team gave it much importance.

Comment Ratio is the ratio of the number of lines of comment to the number of lines in the source code. The initial idea was to address the readability of the source code. Due to a lack of better ideas/ metrics, the comment ratio took the role of the indicator of the readability of source code.

From what I remember, the comment ratio still needed to be included in the project reports during my initial years of work. Later on, they started disappearing slowly. I would be surprised if any organisations would still enforce them!

In my observation of working with several corporate codebases, most comments were hardly useful, with many conveying outdated information. This happened because the comments didn't evolve with the code. If you closely observe, you can figure out that the developers who evolved the code did not bother updating the comments/ documentation because they most likely did not get any benefits from the comments. This, added with the enforcement of the comment ratio metric, made the situation even worse - as the developer who spent time reading the comments only repented for spending time on it.

The comments were less helpful because they explained what the code was doing instead of focusing on why that code exists. Or the purpose of it. After all these years of working in the software development industry, I can confidently say that if a developer cannot write readable code in a programming language, it is hardly possible for them to be able to convey that information in English. That's the reason why comments should focus on the aspects that are not conveyed through the source code.

Though most of the comments are not useful from the information-conveying perspective, some of them were entertaining nonetheless. For example, in a code that parsed email, I found a comment saying - "Eureka, found the body!". The body was an email body! I am sure you had your own moments of reading such comments.

Today, in the era of AI, developers can have the comments generated by GPT-based code assistant tools. But who would be the readers of those comments - the developers or code assistant tools? That would be for the software development teams to answer.

I think the best way to know if the comments are useful is by making a team member read those comments.

Working with the open-source codebase is totally a different experience, though. Unlike corporate codebases, I found the code comments quite helpful. More on code quality of open source codebases is for another day!