One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be harmful.
First off, I think parameter names should be descriptive and self-documenting. If it's not immediately obvious what your parameters are for, you're probably Doing it Wrong. However, I do understand that sometimes it's unclear what a parameter is for, so in those cases, yes, you should write a javadoc comment explaining the parameter.
But I think it's unnecessary to do that for EVERY parameter. If it's already obvious what the parameter is for, the javadoc comment is redundant; you're just creating extra work for yourself. Furthermore, you're creating extra work for anyone who has to maintain your code. Methods change over time, and maintaining comments is nearly as important as maintaining your code. How many times have you seen a comment like "X does Y for Z reason" only to see that the comment is out-of-date, and in fact the method doesn't even take X parameter anymore? It happens all the time, because people forget to update comments. I would argue that a misleading comment is more harmful than no comment at all. And thus is the danger of over-commenting : by creating unnecessary documentation, you're making more work for yourself and everybody else, you're not helping anybody understand your code, and you're increasing the likelihood that the code will have out-of-date comments at some point in the future.
However, I respect the other developer on my team, and accept that perhaps he is right and I am wrong. Which is why I bring my question to you, fellow developers : Is it indeed necessary to write a javadoc comment for EVERY parameter? Assume here that the code is internal to my company, and won't be consumed by any outside party.
Best Answer
Javadoc (and, in the Microsoft word, XMLDoc) annotations are not comments, they are documentation.
Comments can be as sparse as you want them to be; assuming your code is halfway readable, then ordinary comments are merely signposts to aid future developers in understanding/maintaining the code that they've already been staring at for two hours.
The documentation represents a contract between a unit of code and its callers. It is part of the public API. Always assume that Javadoc/XMLdoc will end up either in a help file or in an autocomplete/intellisense/code-completion popup, and be observed by people who are not examining the internals of your code but merely wish to use it for some purpose of their own.
Argument/parameter names are never self-explanatory. You always think they are when you've spent the past day working on the code, but try coming back to it after a 2-week vacation and you'll see just how unhelpful they really are.
Don't misunderstand me - it's important to choose meaningful names for variables and arguments. But that is a code concern, not a documentation concern. Don't take the phrase "self-documenting" too literally; that is meant in the context of internal documentation (comments), not external documentation (contracts).