This week's book giveaway is in the Artificial Intelligence and Machine Learning forum.
We're giving away four copies of Zero to AI - A non-technical, hype-free guide to prospering in the AI era and have Nicolò Valigi and Gianluca Mauro on-line!
See this thread for details.
Win a copy of Zero to AI - A non-technical, hype-free guide to prospering in the AI era this week in the Artificial Intelligence and Machine Learning forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Paul Clapham
  • Bear Bibeault
  • Jeanne Boyarsky
Sheriffs:
  • Ron McLeod
  • Tim Cooke
  • Devaka Cooray
Saloon Keepers:
  • Tim Moores
  • Tim Holloway
  • Jj Roberts
  • Stephan van Hulst
  • Carey Brown
Bartenders:
  • salvin francis
  • Scott Selikoff
  • fred rosenberger

How much Javadoc should we write for the assignment?

 
Ranch Hand
Posts: 49
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Bartender
Posts: 3648
16
Android Mac OS X Firefox Browser Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
For me I write javadoc for all classes, methods, instance variables, etc everything. All access modifiers: private, default, protected and public.

As for how detail, the standard is fine. But for the Data class (the place where the locking, searching etc) probably more details.
 
Alexandru Dragoi
Ranch Hand
Posts: 49
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Ok thanks, if that's what they want me to do, that is what I'll do!
 
Sheriff
Posts: 4889
317
IntelliJ IDE Python Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Alexandru Dragoi
Ranch Hand
Posts: 49
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
K. Tsang
Bartender
Posts: 3648
16
Android Mac OS X Firefox Browser Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Tim Cooke
Sheriff
Posts: 4889
317
IntelliJ IDE Python Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

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.
 
Tim Cooke
Sheriff
Posts: 4889
317
IntelliJ IDE Python Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

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.
 
Alexandru Dragoi
Ranch Hand
Posts: 49
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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...
 
New rule: no elephants at the chess tournament. Tiny ads are still okay.
the value of filler advertising in 2020
https://coderanch.com/t/730886/filler-advertising
reply
    Bookmark Topic Watch Topic
  • New Topic