Stop Writing Code Comments

I think this is horrible advice, and while it’s anecdotal I’ve seen no reason to suggest that not writing code comments leads to higher quality code.

I once managed a developer who at a time could have written this very blogpost. He was also a big fan of the solid principles, and I think he generally wrote good code. I actually also agree with parts of the article. If you name your properties and functions in a reasonable way, then you don’t need a comment telling the future what you put in firstName on an employee object or what getEmployees() does. When it comes to business logic and intend, however, you need to help the future. My developer learned this the hard way when some business logic changed and he had to fix a system he had written a couple of years earlier. Suddenly the once so clear code wasn’t clear anymore, and he had to spent a week reintroducing himself to exactly what intent had gone into making the system. Maybe he was just bad at practicing what he preached, but he started writing code comments after that.

And that’s someone unable to get into their own mindset, it’s much, much worse if the code is handed off to someone else. If I task two developers with solving the same problem, as clear as they possible can using self-explaining code. Well, I’ll get two very different results, because what clear code is, is very subjective.

Respectfully, I think this article contains some really terrible advice. Based on his examples, I think his chief complaint should really be that programmers should stop writing unnecessary comments, which I’m actually okay with.

If you can’t write expressive code, own up to your failure and write a comment. You are responsible for the code you write, so never leave poorly written code unexplained.

While in theory it’s possible that every member of your team could write code that’s so expressive that it never need comment, in reality you’ll find that different programmers adhere to different naming/styling conventions and sometimes being able to see the author’s steps laid out in comments leads easier corrections to errors in logic or better refining of the process itself. Good code commenting practice means that new team members can more quickly adapt to the codebase, or even programmers who are coming back to their older work after some time or a major life event. Invariably there will be times where programmers naturally go through cycles of sprint/crunch and code cleanup, it’s the nature of the work.

Comments don't tell you 'What', they tell you 'Why'.