To play devil's advocate (and be really nitpicky), it doesn't say "return an error" but "return on error" which does contain some useful information: That this method doesn't have any kind of sophisticated error handling but simply aborts on error.
I don't think that's very useful - you see that it doesn't have any kind of sophisticated error handling simply by looking at the method's source code (which you need to do in order to see the comment).
Because it re-states what the code is saying, which makes it two things you wind up reading to absorb one fact. It also create two update points if that code needs be changed.
I prefer that authors spend time to make sure the code is clear about what is happening, and use the comments to tell me why it's happening, and that too only when it's not obvious, or counterintuitive, or there for a special requirement.
Just wanted to point out that comments are not to be confused with documentation as comments, like Javadoc, Godoc strings. These need to be complete and verbose, especially if they code is a library or public.
It just seem quite petty thing to get angry about. Reading those two things takes less then additional half second and on update you can delete the comment if you don't like it. I have seen project behind schedule and it was never because of tiny things like this.
Also, you are likely to find out that comments like this are often result of people just auto-writing them at the moment e.g. writing it was faster then reflect on it. Which is not necessary good thing, but it is saving time in expense of little bit less effective code.
The comment is more a symptom than a cause of problems. If useless comments are added, they’re often an excuse for lazy code, in that it allows a way to say I can’t be bothered to write this better, I’ll just add a comment instead.
Regarding time saving, I seriously doubt that code quality is proportional to time spent typing. Instead of typing two things I would prefer the author spent more time thinking and typing just one thing.
I had a coworker who would write comments like that, it wouldn’t exactly anger me, but it was a bit strange. Why would you go through the trouble of writting a comment like that, but not leave any hints as to what the devil the 50 lines of spagetti code above does? Because that would always be the case: some obvious comment, and nothing for the horribel or complicated stuff.
I've only ever done it with stackoverflow because:
1. I think they'll be around for a long time, and
2. they have that policy of explaining answers on the page rather than just referring to external links (yes - irony not lost on me).
Any future dev looking at my 3-line validateEmailAddress() function who wants to learn about it can go to the site and read about it, and maybe find there's a newer status quo way of validating email addresses.
I suppose you could argue that I should copy the explanation of what the regexp does into the comment but really it's just asking for it to become redundant and if someone really wants to get into it they'll probably benefit from reading the entire up-to-date discussion.
Admittedly this is a very specific kind of situation, but this doesn't feel unreasonable or unprofessional to me (bearing in mind that I'm not generally a copy-paster, I prefer to write my own code but in the case of things like email validation I think it's more professional to find an established algorithm than it is to roll your own, unless you have a specific reason for doing so).
If I cut and paste some code, even if not from Stack Overflow I'll document it. Partly because I want to attribute the code correctly, but also so that someone later can go back to the original source. The original source may have additional documentation, explanations, assumptions, etc. that people in the future may want to know. Plus it helps to know that this block of code is an external cut and paste and that modifying it should be done more carefully than other code.
This tends to only be for tricky or time-consuming algorithms. RGB to HSL/HSV, is point in a polygon, hash function, etc. Those point-in-polygon functions in particular can be densely optimized to the point that it is not obvious a) how it works, b) what the original algorithm was.
The same person that would be able to write readable understandable comment about that horrible and complicated stuff would be also able to refactor it and make it clearer.
That is why. The person left comment on literally one thing in that code he is able to explain.
I sigh often when I read (bad) code. I don't get angry. That, to me, seems to be a bit much. I'm not trying to be judgemental, I just truly don't understand why anger.
