There are a couple of things I do agree with in regards to the comments in code. They aren’t meant as a replacement for documentation. Documentation is still required to explain more abstract overview kind of stuff, known limitations etc. If your class has 3 pages of text in comments at the top, that would probably be better off in the documentation. When working with large teams there are often people who need to understand what the code can and can’t do, how edge cases are handled etc. but can’t read actual code. By writing proper documentation, a lot of questions can be avoided and often help coders as well with a better understanding of the system. Writing doc blocks in a matter that can be extracted into a documentation helps a lot as well, but I feel that does provide an easy way out to not write actual documentation. Of course depending on the situation this might not matter or one might not care, it’s something that comes up more when working in large teams.
Just like writing code, writing proper comments is a bit of an art. I’ve very often seen developers be way too verbose, commenting almost every line with the literal thing the next line does. Anyone who can read the code can see what it does. What we can’t see is why it does this or why it doesn’t do it in some other obvious way. This is something you see a lot with AI generated code, probably because a lot of their training was done on tutorials where every line was explained so people learning can follow along.
This also ties in with keeping comments updated and accurate when changing code. If the comment and the code doesn’t match with each other, which one is true? I’ve in the past worked on legacy codebases where the comments were almost always traps. The code didn’t match the comments at all, sometimes obviously so, most times only very subtle. We were always guessing was the implementation meant to be the comment and the difference just a mistake? The codebase was riddled with bugs, so it’s likely. Or was the code changed at a later point on purpose and the comments neglected?
Luckily these days we have good tools in regards to source control, with things like feature branches, pull requests with tools that allow for discussion and annotation. That way at least usually the origin of a change is traceable. And code review can be applied before the change is merged, so mistakes like neglecting comments can be caught.
Now I don’t agree with the principle of no comments at all. Just because a tool has some issues and limitations doesn’t mean it gets banned from our toolbox. But writing actual useful comments is very hard and can be just as hard as writing good code. Comments also aren’t a cheat card for writing bad code, the code needs to stand on its own and be enhanced by the comments.
It’s one of those things we’ve been arguing about over my entire 40 year career. I don’t think there is a right way. Whatever is best depends on the person, the team, the system etc. And like with many things, there are people who are good and people who suck. That’s just the way the cookie crumbles.
Oof, I felt this in my soul