It’s not a myth, it’s a sound software engineering principle.
Every comment is a line of code, and every line of code is a liability, and, worse, comments are a liability waiting to rot, to be missed in a refactor, and waiting to become a source of confusion. It’s an excuse to name things poorly, because “good comment.” The purpose of variables should be in their name, including units if it’s a measurement. Parameters and return values should only be documented when not obvious from the name or type—for example, if you’re returning something like a generic Pair, especially if left and right have the same type. We’d been living with decades of autocomplete, you don’t need to make variables be short to type.
The problem with AI-generated code is that the myth that good code is thoroughly commented code is so pervasive, that the default output mode for generated code is to comment every darn line it generates. After all, in software education, they don’t deduct points for needless comments, and students think their code is now better w/ the comments, because they almost never teach writing good code. Usually you get kudos for extensive comments. And then you throw away your work. Computer science field is littered with math-formula-influenced space-saving one or two letter identifiers, barely with any recognizable semantic meaning.
No amount of good names will tell you why something was done a certain way, or just as importantly why it wasn't done a certain way.
A name and signature is often not sufficient to describe what a function does, including any assumptions it makes about the inputs or guarantees it makes about the outputs.
That isn't to say that it isn't necessary to have good names, but that isn't enough. You need good comments too.
And if you say that all of that information should be in your names, you end up with very unwieldy names, that will bitrot even worse than comments, because instead of updating a single comment, you now have to update every usage of the variable or function.
>> Every comment is a line of code, and every line of code is a liability, and, worse, comments are a liability waiting to rot,
This is exactly my view. Comments, while can be helpful, can also interrupt the reading of the code. Also are not verified by the compiler; curious, in the era when everyone goes crazy for rust safety, there is nothing unsafer as comments, because are completely ignored.
I do bot oppose to comments. But they should be used only when needed.
No. What you are describing is exactly the myth that needs to die.
> comments are a liability waiting to rot, to be missed in a refactor, and waiting to become a source of confusion
This gets endlessly repeated, but it's just defending laziness. It's your job to update comments as you update code. Indeed, they're the first thing you should update. If you're letting comments "rot", then you're a bad programmer. Full stop. I hate to be harsh, but that's the reality. People who defend no comments are just saying, "I can't be bothered to make this code easier for others to understand and use". It's egotistical and selfish. The solution for confusing comments isn't no comments -- it's good comments. Do your job. Write code that others can read and maintain. And when you update code, start with the comments. It's just professionalism, pure and simple.
For all we know, the comment came from someone who was doing their job (by your definition) and were bitten in the behind by colleagues who did not do their job. We do not live in an ideal world. Some people are sloppy because they don't know, don't care, or simply don't have the time to do it properly. One cannot put their full faith into comments because of that.
(Please note: I'm not arguing against comments. I'm simply arguing that trusting comments is problematic. It is understandable why some people would prefer to have clearly written code over clearly commented code.)
Lead by example! Write comments half a page long or longer, explaining things, not just expanding identifier names by adding spaces in between the words.
I have mixed feelings on this. In most respects, I am a diligent worker who tries to lead by example. On the other hand, part of my work is managing people. While I have employees who follow my example, even when I am not intending my habits to be an example, and I adore those employees immensely -- I also have to face the reality that very few employees do so. They need direction on what is expected. Even then, the direction has to take the form of intense instruction otherwise ... woosh ... the details go over their heads.
That, and I have mixed feelings about commenting code. (Thankfully I don't managed developers. I simply exploit personally since it a skill that I have.) I understand why we do it. I especially appreciate well documented libraries and development tools. On the other hand, I fully understand that comments only work if they are written, read, and updated. The order is important here since documentation will only be updated if it is read and it will only be read if it is (well) written. Even then you are lucky if well written documentation is read.
The flip side is that comments are duplication. Duplication is fine if they are consistent with each other. In some respects, duplication is better since it offers multiple avenues for understanding. Yet there is also a high probability that they will get out of sync. Sometimes it is "intentional" (e.g. someone isn't doing their job by updating it). Sometimes it is "unintentional", since the interpretation of human languages is not as precise as the compiler's translation of source code into object code. (Which is a convoluted way of saying that sometimes comments are misinterpreted.)
Generally, high standards can only be achieved through enforcement, not merely through begging and pleading.
I like to add myself as a mandatory reviewer of all PRs and then reject changes that don't come with some explanatory comment or fail to update comments.
Even if huge swaths of the codebase are undocumented boring boilerplate, you still have to draw the line somewhere, otherwise you get madness like ten pages of authentication and authorization spaghetti logic without a single descriptive comment.
I appreciate your attempt to defend this position and I, and others, wish you good luck. In my many decades of working with humans writing code it simply has never happened.
I've worked at places (early on) that were basically cowboy coding -- zero code review, global variables everywhere, not a comment or test to be seen. Obviously you can't enforce good comments there.
And I've worked at places that were 100% professional -- design documents, full code review, proper design, tests, full comments and comments kept fully up-to-date just like code.
It's just the culture and professionalism. If proper comments are enforced through code review, they happen. Ultimately, the head of engineering just decides whether it's part of policy or not. It's not hard. It's just a top-down decision.
Every comment is a line of code, and every line of code is a liability, and, worse, comments are a liability waiting to rot, to be missed in a refactor, and waiting to become a source of confusion. It’s an excuse to name things poorly, because “good comment.” The purpose of variables should be in their name, including units if it’s a measurement. Parameters and return values should only be documented when not obvious from the name or type—for example, if you’re returning something like a generic Pair, especially if left and right have the same type. We’d been living with decades of autocomplete, you don’t need to make variables be short to type.
The problem with AI-generated code is that the myth that good code is thoroughly commented code is so pervasive, that the default output mode for generated code is to comment every darn line it generates. After all, in software education, they don’t deduct points for needless comments, and students think their code is now better w/ the comments, because they almost never teach writing good code. Usually you get kudos for extensive comments. And then you throw away your work. Computer science field is littered with math-formula-influenced space-saving one or two letter identifiers, barely with any recognizable semantic meaning.