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.
For example: python functions shall have a docstring unless trivial. For external api functions on a class, there must be at least one example. etc etc. Plus, this makes working in ipython really nice!
You could always use a tool like Danger (http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.
This is what code coverage analysis/metrics try to address.
> You could always use a tool like Danger (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.
but they usually are.
I find that I have this problem with my own code. Ridiculous, but it happens.
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.
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.
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.
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.
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.
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.
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?
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.
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.
This is not true of comments.
If we could make outdated comments produce compilation errors, we would live in a wonderful world :)
> If we could make outdated comments produce compilation errors, we would live in a wonderful world
It is impossible. The whole point of having comments (and also identifiers) is to tie the code to things that are not formally described. If we would formally describe them, they would become the code.
You could, at best, mark identifiers in comments (and what their refer to), and then you could use this to hint at comments that need to be updated (as somebody else mentioned). But it will never be a perfect process, because there will always be a boundary between formal and informal.
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.
I really hate it when the compiler ignores my comments.
Depends what language you are working in; in some it won't fail until runtime.
It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.