Overview

A readable and understandable source code should be a balance between:

• Documented complex or not straightforward pieces of code
• Readable unit tests scenarios that will help the developers understand the code
• Documented API that will help external developers understand how to use those API
• Respect of coding standard such as naming conventions

With too many comments, you may face the following issues:

• Time consuming maintenance that may lead to comments that are no longer up to date. Then comments go against their primary goal: they mislead the developer who will spend more time understanding the source code.
• If the source code needs too many comments, it either means that it does not respect coding standards (naming conventions, design, etc.) or it is too complex.

Monitoring Comments

Widget

Add the Comments & Duplications widget to your dashboard:

You can monitor the global comments rate but also metrics like % of documented API.

Coding Rule: Commented-out Code

For many languages, a coding rule is available to detect pieces of code that are commented-out.