Question

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.

No correct solution

Licensed under: CC-BY-SA with attribution
scroll top