4 ms·

Why would a comment like that make you angry?

• spacenick88 8y ago
  Because it adds no value
• sudhirj 8y ago
  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.
  • deleted 8y ago
    [deleted]
  • zeth___ 8y ago
    It doesn't. -1 could mean you're returning a success. I mean that would literally be true in Forth.
    • yoz-y 8y ago
      If the function returns magic numbers then that should be stated in the documentation comment.
    • icebraining 8y ago
      You're showing another problem with these comments: they're often ambiguous. Specifically, the message says "return on error", which to me doesn't mean it returns an error, but to you it did.
  • watwut 8y ago
    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.
    • sudhirj 8y ago
      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.
• mrweasel 8y ago
  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.
  • aaronbrethorst 8y ago
    (they didn't understand what their 50 lines of spaghetti did...otherwise they would've written a pithy comment explaining it.)
    • SmellyGeekBoy 8y ago
      Indeed. "// This was copy and pasted from Stack Overflow. I have no idea how it works." doesn't come across as very professional.
      • jclulow 8y ago
        I believe that comment is required by the licence terms of code cribbed from Stack Overflow, though.
      • firmgently 8y ago
        I've on rare occasion written a comment along the lines of: // based on stackoverflow.com/questions/201323/how-to-validate-an-email-address-using-a-regular-expression because I'm not going to pretend to have written this monster myself: (?:[a-z0-9!#$%&'+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'+/=?^_`{|}~-]+)|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])")@(?:(?:[a-z0-9](?:[a-z0-9-][a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-][a-z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]) 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).
• tzahola 8y ago
  Because comments like that accompany the most trivial bits of the codebase, while the thousand line monkey-patched crap has zero comments.