4 ms·

I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code

I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.

wnevets 10y ago
>Comments are no exception. but they usually are.
- joekrill 10y ago
  Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.
  - BigJeffeRonaldo 10y ago
    It's a matter of incentives. Business folks don't care about comments unless they have a dev background. Your options are then to focus on the incentives present in the situation, or materially harm your own life and well-being by working extra hours to make up for your management's inability to manage.
    - vinceguidry 10y ago
      I hate this excuse. It seems like every lazy habit of programmers gets pushed onto the "business folks". Just because business folks don't know how to value certain developer practices doesn't let you off the hook. Just do what you have to do and if it takes longer because you had to learn how to do it, then it takes longer. Let the business folks tell you when it's taking too long to deliver features.
      - BigJeffeRonaldo 10y ago
        But it does. It depends on the organization, but there are groups where chugging coffee, talking a lot, and pumping out dozens of half-working features by coding like a drunk cowboy will get you promoted and recognized as a team player, while pushing back to take time and do things right will have you reprimanded. Many such cases out there.
        vinceguidry 10y ago
        My point is that you shouldn't push back. Just do things the way they need to be done, and it takes as long as it takes. A manager looks at a programmer bringing up something like unit testing as "why the fuck is he asking me about this, it's his job? Obviously because he's asking me it's outside of his professional ken, so that means it's going to take absolutely forever." Out loud he'll just say, "Can you just get the feature done?" Don't ask, just do it. It takes as long as it takes. If they ask, just say it's not done yet.
        BigJeffeRonaldo 10y ago
        This generally won't work for straight forward game theoretic reasons. Boss thinks you're slow->boss brings on h1b consultant willing to pump out spaghetti code and toady up to him->you looking for a new job. Organizations get what they ask for
        vinceguidry 10y ago
        The boss doesn't have to think you're slow. You could... gasp... be good at your job.
        BigJeffeRonaldo 10y ago
        I can tell you're upset, Vince, so I'll be the one to end this discussion.
        MaulingMonkey 10y ago
        Being good at your job won't magically make you fast at fixing up other people's spaghetti code. It won't let you ship 3 working features faster than someone else who's also "good" at their job ship 6 mostly broken features. It won't convince your manager that the former is actually getting more work done than the latter, and won't prevent them from thinking the first guy is slow and the second guy is fast. But for what it's worth, I agree with you in that I'm still on the hook. Either to help educate my manager, or to pick managers who already understand this stuff.
    - Johnny555 10y ago
      In my company, the business folks have no idea what the code looks like or whether or not there are comments. All they care about is that the code works, and that features can be delivered on time. That second part "delivered on time" includes maintaining the comments along with the code since it makes the code more readable, and eases future changes. If Management doesn't give you time to write maintainable code (which includes keeping comments in sync with the code), then you may as well start looking for a new job because the technical debt is going to pile up and it's going to get harder and harder to meet deadlines.
    - emodendroket 10y ago
      They don't care about comments, per se, but they probably care about whether someone else can easily work on the code. I'd think (hope) most technical managers are going to encourage some sort of team review of the code and not get all the way into the weeds about what specific issues in the code review need attention.
  - dhimes 10y ago
    Would be cool to have a utility that embeds a hash of the function in the comments, and could check automatically. So if a function changes and hash doesn't the user would be alerted. I find that I have this problem with my own code. Ridiculous, but it happens.
sparky_z 10y ago
The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check. In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.
- lisivka 10y ago
  To miss comments in the code, developer must be blind. Maybe you are telling us about sad story of external documentation?
  - lgas 10y ago
    This isn't true, especially when you're dealing with legacy code that is overcommented. Your brain will learn to tune them out.
- joekrill 10y ago
  But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test. Does that mean we should just abandon writing unit tests altogether? You could always use a tool like Danger (http://danger.systems/ http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.
  - MaulingMonkey 10y ago
    > But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test. This is what code coverage analysis/metrics try to address. > You could always use a tool like Danger (http://danger.systems/ http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been. I'd worry about tuning out said warnings after too many false positives. Comments regular enough to not generate too many false positives can generally be turned into real syntax of some description.
tigershark 10y ago
Unit tests fail when they are out of sync. Guess what? An out of sync comment will never fail.

wnevets 10y ago

>Comments are no exception. but they usually are.

joekrill 10y ago
Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.
- BigJeffeRonaldo 10y ago
  It's a matter of incentives. Business folks don't care about comments unless they have a dev background. Your options are then to focus on the incentives present in the situation, or materially harm your own life and well-being by working extra hours to make up for your management's inability to manage.
  - vinceguidry 10y ago
    I hate this excuse. It seems like every lazy habit of programmers gets pushed onto the "business folks". Just because business folks don't know how to value certain developer practices doesn't let you off the hook. Just do what you have to do and if it takes longer because you had to learn how to do it, then it takes longer. Let the business folks tell you when it's taking too long to deliver features.
    - BigJeffeRonaldo 10y ago
      But it does. It depends on the organization, but there are groups where chugging coffee, talking a lot, and pumping out dozens of half-working features by coding like a drunk cowboy will get you promoted and recognized as a team player, while pushing back to take time and do things right will have you reprimanded. Many such cases out there.
      - vinceguidry 10y ago
        My point is that you shouldn't push back. Just do things the way they need to be done, and it takes as long as it takes. A manager looks at a programmer bringing up something like unit testing as "why the fuck is he asking me about this, it's his job? Obviously because he's asking me it's outside of his professional ken, so that means it's going to take absolutely forever." Out loud he'll just say, "Can you just get the feature done?" Don't ask, just do it. It takes as long as it takes. If they ask, just say it's not done yet.
        BigJeffeRonaldo 10y ago
        This generally won't work for straight forward game theoretic reasons. Boss thinks you're slow->boss brings on h1b consultant willing to pump out spaghetti code and toady up to him->you looking for a new job. Organizations get what they ask for
        vinceguidry 10y ago
        The boss doesn't have to think you're slow. You could... gasp... be good at your job.
        BigJeffeRonaldo 10y ago
        I can tell you're upset, Vince, so I'll be the one to end this discussion.
        MaulingMonkey 10y ago
        Being good at your job won't magically make you fast at fixing up other people's spaghetti code. It won't let you ship 3 working features faster than someone else who's also "good" at their job ship 6 mostly broken features. It won't convince your manager that the former is actually getting more work done than the latter, and won't prevent them from thinking the first guy is slow and the second guy is fast. But for what it's worth, I agree with you in that I'm still on the hook. Either to help educate my manager, or to pick managers who already understand this stuff.
  - Johnny555 10y ago
    In my company, the business folks have no idea what the code looks like or whether or not there are comments. All they care about is that the code works, and that features can be delivered on time. That second part "delivered on time" includes maintaining the comments along with the code since it makes the code more readable, and eases future changes. If Management doesn't give you time to write maintainable code (which includes keeping comments in sync with the code), then you may as well start looking for a new job because the technical debt is going to pile up and it's going to get harder and harder to meet deadlines.
  - emodendroket 10y ago
    They don't care about comments, per se, but they probably care about whether someone else can easily work on the code. I'd think (hope) most technical managers are going to encourage some sort of team review of the code and not get all the way into the weeds about what specific issues in the code review need attention.
- dhimes 10y ago
  Would be cool to have a utility that embeds a hash of the function in the comments, and could check automatically. So if a function changes and hash doesn't the user would be alerted. I find that I have this problem with my own code. Ridiculous, but it happens.

sparky_z 10y ago

The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check. In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.

lisivka 10y ago
To miss comments in the code, developer must be blind. Maybe you are telling us about sad story of external documentation?
- lgas 10y ago
  This isn't true, especially when you're dealing with legacy code that is overcommented. Your brain will learn to tune them out.
joekrill 10y ago
But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test. Does that mean we should just abandon writing unit tests altogether? You could always use a tool like Danger (http://danger.systems/ http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.
- MaulingMonkey 10y ago
  > But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test. This is what code coverage analysis/metrics try to address. > You could always use a tool like Danger (http://danger.systems/ http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been. I'd worry about tuning out said warnings after too many false positives. Comments regular enough to not generate too many false positives can generally be turned into real syntax of some description.

tigershark 10y ago

Unit tests fail when they are out of sync. Guess what? An out of sync comment will never fail.