Copy & Paste & Never Update

Sometimes Javadocs are simply there, because they were in another method. And so they came here when developer copied & pasted the code along with Javadocs. Of course, they were never updated to reflect the semantics of the new method. And now the documentation lies. Like this:

As pointed out to me by Łukasz D. (thank you!) stuff like mBit may be some fundamental concept of the business domain, and is probably explained in detail in some other documentation (hm... is there any other documentation?). Maybe so, but anyway, to have an entry for name and no entry for mBit is kind of a cruel joke, don't you think?

Conclusions

What can I say? As proved by the examples above it is pretty simple to write Javadocs, and I would say it is even fun. I can do it, you can do it, his grandma can do it, and her cat can do it as well. So let us write more of this stuff, because that is what programming is all about! ;)

Some projects policies require javadoc on every public method. Some of these comments are probably result of such policy. What are you going to write on top of "public Resource()" if you have to? It creates the object ... really ... not much more.

You are right, it may happen that such Javadocs appear because of such stupid policies imposed. But the examples I gathered are of different breed (AFAIK, the projects the code comes from had no such policies) - they are rather a result of the lack of experience (or cluelesness) of devs.

Anyway would be useful to have example of useful javadocs.
In general comments are another piece of code that needs maitenance, maybe is better to write so called self-documenting code? What do you think? Does it exist really?

Self documenting code has its perks. For instance naming the parts of a dog tail, nose, ears, eyes etc is much better than naming them a, b, c and d respectively. That's when documenting will become necessary to explain what they mean.

On another note, the above are all examples on where comments are completely unnecessary. If someone does not know what a constructor looks like, he's going to have problems reading the code in any case. Personally, the places where I don't mind comments are when they describe difficult to understand algorithms or explain what a non-trivial function does if the usage is not obvious.

Personally I use comments mostly to remember why I solved a particular problem a certain way, especially when I've had a hard to find bug. In java.swing some components' functions need to be called in a certain order for the component to work properly and it is good to remember not to change the order.

(Although mostly excellent the java api is riddled with what could be defined as bad or useless comments. Look for instance at class java.awt.Color; is it really necessary to explain that the field static Color BLACK is The color black?)

When one writes any method documentation, one should document the purpose of the documentation, the preconditions on its arguments, the invariants the method will maintain, and the postconditions on the result and the objects.

If one is using a validator system like JSR 303, one can write code like

Even if one doesn't actually configure a validator for the project, or uses AOP to validate, the annotations appear in the Javadoc pages, and a user has a fighting chance to understand the constraints on the constructor. There will be no need to add {@code firstName} must not be {@code null} to the @param tag.

Even private methods could have Javadoc, if only to document assumptions, techniques, and strategies. Why is the programmer using a LinkedList instead of an ArrayList? Why is this String not internationalized?

JSR 303 defines the javax.validation package, and there are two implementations; the Hibernate Validator, and Apache BeanValidation. The difference between using these validators and using tests is that the validators run on demand, while testing input runs whoever someone constructs or mutates an instance. Consider the duplication in:

public void setGivenName(String givenName) { // If block from constructor nearly repeated. // Do not have the constructor call a public non-final method. // Somebody might override it. // But, do you really want setters?}

Do you want to validate right away, or just when you use the Name instance? Will this make a UI too finicky? Also, what happens when your business rules change, and you need to change '20' to '30'?

We're using the Hibernate validator at my work project. It does very well. One can also override the annotations through a xml file to change the business rules. The annotations in the constructor are really for documentation only, but see below. In reality, one writes:

and then the call validator.validate(name) checks and returns a collection of errors. There's a glue project for Apache Wicket that turns this into Wicket validation errors; this cuts 50% of the work.

On the other hand, if you use AOP, either through AspectJ, or through Spring AOP, you can create pointcuts matching calls with annotated arguments, and before advice to check those arguments, possibly throwing a NPE or IAE. The advantage again is that you can get the boilerplate code out of the method calls. Of course, AOP will confuse junior developers. The Apache validator has a way to do this too, but AspectJ has other useful roles too.