After many years of experience in development/leading, different programming teams with different skill sets. I always recommend using a good amount of descriptive comments on the implementations. Therefore, others can understand the purpose and uses of it.
However, I found that it is not the right choice much time. These days, I usually ask other people to remove mostly all their comments in code review. This post will talk about the reason why I do so.
Comments Lie
That fact may surprise people, but there are many cases the comments lie. To explain that, let’s think about a case where different developers modify the code as per the business requirement but they forget to update the comments while changing the behavior of the function/feature. I personally find this true when implementation is old and people usually do changes for fixing the bugs or making changes for updated requirements.
Writing comments demotivate from writing descriptive/clean code
While the comments can describe the code pretty well, they also discourage developers from thinking and writing code more descriptively. If the developer forced himself to remove all comments but still ensure readability, he might come with a better version.
Instead of commenting on each step, he applied guidelines from clean codes:
- Use small functions. Each function came with a single responsibility.
- Use a descriptive name for all functions and variables.
They are small changes but can make his code much more clean and clear. In addition, I can be sure that other people can understand this code without any comment in the first sample.
Writing UnitTestCase Is Safer Way To Explain Feature
Most of the case, we can describe the functionality of a function using its unit tests. If you still see some hidden logic, it’s more likely that you should add more tests. Using tests strictly also helps for code review.