Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
    
Many Java IDEs (Intellij in particular) will tag a missing Javadoc parameter as a documentation warning –  Gary Rowe May 12 '11 at 9:31
    
NetBeans and Eclipse will, too. –  Davor Ždralo May 11 '12 at 1:18

6 Answers 6

up vote 17 down vote accepted

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

share|improve this answer
1  
+1: It's as essential as the code itself. It just doesn't have good automated testing. –  S.Lott May 11 '11 at 19:55

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

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
1  
+1 for a good way of looking at it –  Gary Rowe May 12 '11 at 9:34

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.

share|improve this answer
    
Does "a - the argument whose absolute value is to be determined" really add anything to the documentation of Math.abs? –  kevin cline May 12 '11 at 4:15
    
@Kevin cline could be useful for the hard of thinking ;-) –  Gary Rowe May 12 '11 at 9:33

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

share|improve this answer
4  
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 –  Demian Brecht May 11 '11 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. –  Tim Williscroft May 12 '11 at 0:11

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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