| There are too many comments in there. Comments are not the first tool people should try to reach because: 1. That's a lazy way to make the code clear, most code should be self-descriptive. If the teams are spamming comments it's likely to be a bad code base already. 2. There's no guarantee the comment is compatible with the code: It's natural language and there's no obvious way to test that. After versions of modification, the comments might still look like they make sense but that's not how the code work anymore. Two alternatives: 1. Declarative programming: Try to leverage declarative programming styles more. For example, top-down style dynamic programming or memoization is always more readable and less error-prone than the bottom-up ones. You don't have to fully adopt functional programming or logic programming, but do take some inspiration from them. 2. Testing. Tests are like comments, they reflect some meaning of the code. Tests are not like comments, if the code breaks, they break. Of course, comments are very valuable, but it's most valuable when applies in the right spots only. |