This week's book giveaway is in the Mac OS forum. We're giving away four copies of a choice of "Take Control of Upgrading to Yosemite" or "Take Control of Automating Your Mac" and have Joe Kissell on-line! See this thread for details.
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.
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.
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.
Tim Driven Development
Joined: May 09, 2008
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.
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.
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.