11 ms·

The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have

• joekrill 10y ago
  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.
        • 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.
• schmichael 10y ago
  This is a reason to check comments in code reviews not to avoid comments completely.
• macintux 10y ago
  The danger of stale comments is, I feel, overblown. First, other developers know that comments can grow stale, so they're unlikely to treat them as sacrosanct, although I admit to falling into that trap. More importantly, most of the types of comments that Eric recommends can drift out of sync with the code and still be useful. Why is this code here? What happened previously that is no longer in the code? What tradeoffs have been chosen?
  • mpweiher 10y ago
    > The danger of stale comments is, I feel, overblown. Yes, because they should be, and are, largely ignored. Of course, deleting them is better than ignoring and not having them in the first place is better than deleting.
    • sqeaky 10y ago
      What about comments that actually help and are accurate, is there no value to that?
• js8 10y ago
  As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.
  • derefr 10y ago
    Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. This is not true of comments. If we could make outdated comments produce compilation errors, we would live in a wonderful world :)
    • ntsb 10y ago
      > If we could make outdated comments produce compilation errors I really hate it when the compiler ignores my comments.
    • sqeaky 10y ago
      But it could. With C++ at least you can get your build to break on some comment errors. If you enable Clang's pedantic warnings, or if you setup Doxygen to emit warnings in the same format as your compiler and incorporate Doxygen execution directly into your build, you can get errors and warnings on bad comments. Doxygen supports documenting function parameters, C++ template parameters, return values then Doxygen and Clang can tell if the name listed for some of those things doesn't match the actual code or if a certain kinds of comments are missing. This won't tell you the documentation is wrong, but it would stop you from adding or removing a function parameters while ignoring documentation comments entirely. If you want to go crazy you can write Clang plugins using LibTooling and run and code you want and analyze the comments any way you choose.
    • emodendroket 10y ago
      > Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. Depends what language you are working in; in some it won't fail until runtime.
    • 10y ago
• RangerScience 10y ago
  I feel like this translates to "lazy* developers are a problem" rather than "comments are a problems". Snarkily, how lazy* do you have to be to not even delete comments you make stale? * And not as in the virtues of programming lazy.
  • sqeaky 10y ago
    It seems to me this is more of a knowledge issue or even a code/discoverability issue. The closer a piece of documentation is to the code the more likely it is to be updated. External manuals always become stale and comments in C headers are more likely to be stale than comments next to the implementation in C source files (or in any language that doesn't even have that distinction). Comments directly next to complex formulae or other technical BS are most likely to be correct. Some learn that then suggest getting rid of all comments or putting comments throughout all the code, but if we look at it another can can infer that some of it is code structure problems. A 2k line class with 200+ line methods with comments at the beginning of each method is more likely to have stale comments that any number of tiny classes with 10 line methods. Then comments on a 10 line method are more likely to be read too, because they need to describe less. Ideally they just add the "why" to the "what" the method's name provides. If the whole method and all the comments fit on the same screen then the dev ignoring it must be truly lazy.
• ng12 10y ago
  If you update code without updating the comments and it gets past review you have bigger problems than them being misleading. Good comments are dependent on good developers.
  • sqeaky 10y ago
    Good results of any kind are dependent on good developers.
    • ng12 10y ago
      Right, but the point is more that bad developers can ruin any good methodology.
• DrScump 10y ago
  The code gets updated but the comments stay the same. It's especially sad when such practices survive code review. Reviewers, that's a symptom you aren't really reviewing what's going on.