So you are usually better of reading the code anyway because you cannot trust that some dev updating code updated javadoc as well.
When something goes wrong I usually have to do is to dig into GIT history and see when and what changes were connected.
The most reliable Javadoc is @author, git tells you the author, @author tells you who the code was copy/pasted from.
Names do become misleading. Of course making callstack deep enough, will hide that.
Code reviews have same power to rectify both: naming and comment issues.
Great point.. except for when you're dealing with a lead and/or reviewer that refuses to approve comments because "we write self-documenting code" yikes
The problem is that someone on your team drastically changes existing methods behavior instead of writing new ones, and by doing that, is changing the behavior every historical caller expected.
I really think that if your changes are so important that they need the doc to be updated, it’s probably that you should write a brand new method. Changes in an already called method should only concern implementation details.
It is about people. In the world where team members last ~2 years and move on, expecting that documentation is left not updated is in my opinion perfectly valid assumption.
> If you wonder what the method does, or what the valid input range for a parameter is, you are better off just reading the code to see what it does.
I feel that this is a very inefficient approach to coding. If you tell me what the function does, what its valid inputs are, and what it returns then I don't need to look at the code at all.
More so when I'm collaborating with people outside my area of expertise: a colleague of mine wrote a function to "convert molecule SMILES into their neutralized form". What does it do? Beats me, I'm not a chemist. But thanks to the comments I don't need to know, and I'm grateful for that.