Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?

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.

Answer 1

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).

Answer 2

Either comment everything or comment nothing (obviously commenting everything is a much better choice). Think about someone using your code, either reviewing your API directly in your source file or in a generated doc file (i.e. doxygen output). Inconsistencies generally lead to confusion, which leads to time spent digging through source to figure out why something wasn't commented, which leads to wasted time that could have been avoided had the parameter just been commented in the first place.

Remember: Something that makes sense to you may be interpreted completely differently by someone else, no matter how mundane you think it is (think about someone who isn't as strong in English reading through and trying to understand your code).

Having said all that, if the other developer is stressing the importance of documenting everything, then just as much emphasis (if not more) needs to be put on keeping the documentation up to date. As you stated, there's not much worse than having out-dated comments (just as bad, if not worse than omitted docs).

Answer 3

Let's start from the assumption that developer cycles are the resource we are trying to conserve.

So that means that devs shouldn't waste time documenting self-evident parameters and return values, right?

Well, let's break it down.

If we document everything, assuming the marginal comments really are trivial and require no thought or research, the cost is the added time to actually type the comment and fix typos.

If we pick and choose, then the costs are:

• Having and winning the argument with the other developer(s) on your team who think everything should be documented.
• For each parameter, determining whether this should or should not be documented.
• More arguments with your team when someone has a different opinion on whether a parameter should have been documented.
• Time spend hunting down the code and researching when a parameter that was deemed self-explanatory turns out not to be so.

So, I would be inclined to just document everything. The downside is definite, but is contained.

Answer 4

If you're writing Javadoc anyway, you might as well write it completely, even including the "obvious" parameters. They may be obvious to you or the other developer, but anyone new that is looking at it would benefit from knowing the intention of each parameter.

As for maintaining Javadoc properly, you need to use tools for your development that help you with this. Eclipse comes to mind. Of course, if it's important, you must ensure that everyone on the team does their part to maintain the code, including comments.

Answer 5

Don't forget that javadoc can be made visible while separate from the code, prime example being the Java API itself. By not including the javadoc for every parameter in a method you are misrepresenting the method and how it might be used.

Answer 6

Some people tell you should document all methods and all arguments. However from a practical point of view 99% of arguments are obvious. But that 1% should be taken care of. If you go again again to learn about a method arguments, you should document them so that the IDE will help you out.

Also something worth noticing is that you can not write anything the best way the first time. That is why it is good to just see how you work with the code and than expand documentation if needed.

If you don't see any problem with arguments, it may be hard to decide what has to be described. Than a new team member can do it. To acomplish it your team has to embrace a culture where everyone is allowed to expand code documentation. That way, a new team member can add value by documenting arguments he found hard to understand.

That way you lower time to read system increasing your team overall productivity and happiness both for existing members and new ones.

Answer 7

'necessary' is completely subjective. I think what you are asking is, 'in your situation, should you add a javadoc comment'. Not knowing the scope or context of your app, how are we to know whats appropriate for you?

If this public facing code (ie, code meant for others to access, such as an api) then yes, document every single parameter. Dont assume the reader knows about the project as much as you do. But otherwise, its up to you and your team to make your own decisions.