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.