[dvddgld]

I like your article and the example you used, code clarity is vital. Poor code is often accompanied by many poor comments which only helps in overwhelming the next poor soul who has to read the code.

However, I think that the larger the project, the more sense it makes to comment heavily. Again, code clarity needs to be a priority, but so does comment clarity, so much time is spent reading code by humans who are optimized to parse natural language. So we should cater to our users, not just the users of our executable, but the users of our source too!

[antonpug]

Some commenting is okay and necessary. The point is that generally, if you are adding heavy commenting, you can probably refactor the code in such a way that commenting is not necessary. Even in a large codebase.

[dvddgld]

I agree that heavy commenting can be a code smell