I completely disagree. Your first example is just way to forced and imho not applicable at all. Why was that comment written wrong? Wouldn't the dev then also name the function wrong? If the function is named wrong the same applies as it did for the wrong comment.
The example with comment why and not how, I can get behind somewhat. Although again a bad example imho. As that comment to why should not be placed in the function but where it is used instead. Because if the comment is added within the function you could easily use it at someplace else where you have a second use case for the same functionality. If the first use case now changes a dev might be inclined to just change that function because it states the use case in the comment. Maybe breaking that second use case.
I agree we need good comments but in my experience I never came across a piece of code and thought to myself: "That's to many comments". So I don't think a call for action for less comments is what we need.
Usually it's not that the comment is written wrong, but that the code changes over time and the comment isn't updated to reflect that. I'm sure somebody will argue "well don't do that", but that doesn't really reflect the reality of the situation most of the time.
Usually if the code is self descriptive it's better because then it's an atomic operation. As the code changes the high-level descriptor of what that code is doing also changes (hopefully anyways).
Either way, my point isn't to defend or oppose the article, but just to point out that incorrect comments are a very real problem on projects.
Learn something new every day.
- I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Location
Buenos Aires
Education
Computer Science Degree at Universidad de Buenos Aires
I completely disagree. Your first example is just way to forced and imho not applicable at all. Why was that comment written wrong? Wouldn't the dev then also name the function wrong? If the function is named wrong the same applies as it did for the wrong comment.
The example with comment why and not how, I can get behind somewhat. Although again a bad example imho. As that comment to why should not be placed in the function but where it is used instead. Because if the comment is added within the function you could easily use it at someplace else where you have a second use case for the same functionality. If the first use case now changes a dev might be inclined to just change that function because it states the use case in the comment. Maybe breaking that second use case.
I agree we need good comments but in my experience I never came across a piece of code and thought to myself: "That's to many comments". So I don't think a call for action for less comments is what we need.
~Cheers
Usually it's not that the comment is written wrong, but that the code changes over time and the comment isn't updated to reflect that. I'm sure somebody will argue "well don't do that", but that doesn't really reflect the reality of the situation most of the time.
Usually if the code is self descriptive it's better because then it's an atomic operation. As the code changes the high-level descriptor of what that code is doing also changes (hopefully anyways).
Either way, my point isn't to defend or oppose the article, but just to point out that incorrect comments are a very real problem on projects.
exactly . comments are dead. Code is alive