I think the source of the problem with comments is that we try to make them serve two purposes: 1) Give the code clarity 2) Be the source of documentation Th

I think the source of the problem with comments is that we try to make them serve two purposes: 1) Give the code clarity 2) Be the source of documentation These goals aren't easily reconciled, too many comments reduce clarity whilst increasing the likelihood that they are inaccurate and not maintained. Documentation generated from comments seldom explains how to use the APIs that a library or program exposes. Usually resulting in the addition of more comments, further reducing code clarity. The real problem with comments is that too few of us write useful documentation. I can't remember who said that the best thing a programmer can do is to learn to write. Our job isn't just to write code, it's also to make sure the code is used... meaning we need to learn how to sell our code to people who will maintain and implement things against our interfaces. We need to sell to other devs, by documenting better and explaining how to use our code. Only then can we reduce the in-line comments that reduce readability of code.