How much Javadoc should we write for the assignment?

I guess that writing Javadoc is mandatory for the exam, but how much should we make use of it?
For public APIs I see the use of these type of comments, but is there a rule that compels us to write Javadoc for every public method (or even for private methods)?
In the exam book that I use to prepare myself I see extensive use of Javadoc comments.

If I will lose points because I do not document every method that I write, then this will be a terrible scenario: I will have to write redundant comments, where method names and parameters names (and even the code itself) are self explanatory.

For me I write javadoc for all classes, methods, instance variables, etc everything. All access modifiers: private, default, protected and coderanch.

As for how detail, the standard is fine. But for the Data class (the place where the locking, searching etc) probably more details.

Ok thanks, if that's what they want me to do, that is what I'll do!

I understand that this post is in the Certification forum so you're probably more interested in what the Marking Criteria guidelines are for JavaDocs. I cannot help you there.

However, I do tend to take the opposite view of things than K Tsang does. I write as little JavaDoc as possible. Which means with the exception of 'public' API's I mostly write none. I'll back up my viewpoint with some examples:

Example1: Instance variables.

The JavaDoc tells us nothing about the variable that the variable name doesn't. But now my variable declaration takes up 4 times as much space as it needs.

Example2: Field accessors.

The JavaDoc tells us nothing about the method that the method signature doesn't. But now my accessor code occupies over double the amount of space it needs to.

Example3: Methods

In this case you might think that the JavaDoc has value as it describes what the method does. While this is true I don't see it as the positive point you might think. I see that the JavaDoc is covering up the fact that we have a poorly named method that does not reveal its intent with a meaningful name. For this example I would refactor to the following:

Uncle Bob Martin has a whole section in his book Clean Code about JavaDoc, Comments, and naming. Well worth a read.

This is also what I wanted to emphasize in my original post.
Code is changing rapidly these days, and you do not have time to update also the documentation in order to keep up with the code.
It is better to concentrate on how to make your code to be easy to read rather than to add tons on documentation.

But I guess that for such a small project (required by OCMJD), writing a lot of Javadoc (even for privates), it is not such a pain.

Tim's comments are also correct. Yet I doubt file size is an issue. A one liner plus those @XXX attributes eg @param, @throw, @return etc are alright.

When you are done with the javadoc, you have the option to generate just the public methods or all (including private).

The javadoc portion is part of the "documentation" criteria, which I believe includes the user guide, the choices.txt (probably most important doc) and javadoc.

Alexandru Dragoi wrote:and you do not have time to update also the documentation in order to keep up with the code

It's potentially worse than that. Take this example again:

Let's say that the business decides that it's not blue Widgets that are important anymore, it's red ones. The developer comes along and finds that this method is tasked with finding the blue Widgets, thinks "great, all I need to do is change this method to find red Widgets instead". This will almost certainly be the result:

It works! You're happy. QA are happy. The Business Analyst is happy. The customer is happy. Job done. Move on.

But what's wrong with this picture? That's right, the JavaDoc still says it's counting blue Widgets. Now the documentation is lying to you, which is much much worse than having no documentation at all. You might think this JavaDoc neglect is laziness. Maybe it is. But the reality is that this happens all the time.

I'd rather have no JavaDoc than JavaDoc that lies to me.

K. Tsang wrote:Yet I doubt file size is an issue.

No. File size is not the issue. Code readability is the issue. When there's lots of unnecessary JavaDoc and Comments it takes a good deal of cognitive load to visually sift the Wheat (code) from the Chaff (redundant comments) which takes away from your ability to think about what code is doing and what you're supposed to be doing with it.

Well it seems that they have strict requirements for the exam. I found this forum discussion, Javadoc for getters/setters:

javadoc style comments must be used for each element of the public interface of each class

Public, protected and package-private are part of the public interface for each class. At least they do not require to document also private members...