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.

  • Many Java IDEs (Intellij in particular) will tag a missing Javadoc parameter as a documentation warning
    – Gary
    Commented May 12, 2011 at 9:31
  • NetBeans and Eclipse will, too. Commented May 11, 2012 at 1:18

7 Answers 7


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

  • 1
    +1: It's as essential as the code itself. It just doesn't have good automated testing.
    – S.Lott
    Commented May 11, 2011 at 19:55
  • If the parameters for a method include e.g. three pairs of X and Y coordinates which will be interpreted as adjacent corners of a parallelogram, is it more useful to have six little pieces of documentation, one for each parameter, or to describe the purpose of the method in terms of parallelogram (x1,y1), (x2,y2), (x3,y3), and (x1+x3-x2,y1+y3-y2) [the latter being opposite (x2,y2)]? If the purpose of the method is defined in terms of parameter names, I would think additional documentation about the parameters would in many cases be superfluous.
    – supercat
    Commented Feb 6, 2015 at 20:10
  • 1
    @supercat: I'd argue that in such a case, you should be refactoring, such that you have a single data type, Point, and the function simply takes three Points (or better yet an array/iterable of them). The more parameters a method has, the more unwieldy it is to call and the more unstable its specification tends to become over time.
    – Aaronaught
    Commented Feb 7, 2015 at 19:56
  • @Aaronaught: That depends a lot on how the method will be used. Having an overload that receives three Point, and one which receives a Parallelogram, may be helpful if many callers could pass such things through. If, however, a lot of Point instances would end up being constructed for no purpose but to be passed to the method once, then constructing the objects would make code both slower and harder to read. If a language supported aggregates which would be and behave as a bunch of values stuck together with duct tape, and one could pass a parameter of aggregate type merely by...
    – supercat
    Commented Feb 7, 2015 at 21:37
  • ...enclosing the values in braces, then that could be good from both a performance and readability standpoint. Java has no such concept; a JVM-based language could support such a thing efficiently for parameters (a parameter Point p1 could be translated into int p1_x, int p1_y), but the JVM has no efficient mechanism for a function to return such a thing.
    – supercat
    Commented Feb 7, 2015 at 21:41

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


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.


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.


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.

  • Does "a - the argument whose absolute value is to be determined" really add anything to the documentation of Math.abs? Commented May 12, 2011 at 4:15
  • @Kevin cline could be useful for the hard of thinking ;-)
    – Gary
    Commented May 12, 2011 at 9:33

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.


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

  • 6
    I find that even if it's not public facing, it helps me to understand my own code when I look back on it years later :P Commented May 11, 2011 at 19:17
  • 1
    This approach is also known as the "Heck we'll make the new guy have to read the damn code in 4 years after we've gone." approach. Commented May 12, 2011 at 0:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.