Running javadoc comments

Question

I read a lot of articles about javadoc, but still can't die when the "template" begins. In this example:

/** * Returns a list of tasks for specific user * @param userId * @return Selected list of tasks */ List<Task> getTasksForUser(Integer userId); /** * Returns a list of tasks in chosen month and year * @param month * @param year * @return selected list of tasks */ List<Task> getTasks(Integer month, Integer year); 

Can I somehow make them fewer templates or should I just delete them?

Why do we have repetitions in 75% of the articles called "Best Practices for Javadoc"? For example:

 /** * Returns a list of tasks using params month, year * @param month * @param year * @return a list of tasks */ List<Task> getTasks(Integer month, Integer year); 

Doesn't he write 2 times one thing?

Answer 1

To a certain extent, we are talking about "style." However, let's see:

 /** * Returns a list of tasks for specific user * @param userId * @return Selected list of tasks */ List<Task> getTasksForUser(Integer userId); 

Some people argue that there is some merit in

• a human read description that tells you what the method does
• More info with @ param / @ return tags

You can, for example, rewrite this as:

 /** * Returns a list of tasks for specific user. * @param userId denotes the user by his numeric id * @return Selected list of tasks (maybe empty, never null) */ List<Task> getTasksForUser(Integer userId); 

So, in your example, there is a place to use additional tags to provide virtually different information: each line in my version performs a specific purpose, while your example simply repeats the same information, although it uses a slightly different wording.

But, as said, in the end, it is a matter of style, and the key point is that you should choose the “style” that you (and your peers) consider the most useful for your context.

And note: instead of repeating the “obvious” things over and over, a more useful comment might look something like this:

 /** * @return The tasks selected for the given user (maybe empty, never null) * @throws UnknownUserException when <code>userId></code> is not known */ List<Task> getTasksForUser(Integer userId); 

Which is basically “my” preferred style - go with a single @return line. But instead, pay attention to such important aspects as: this method throws this exception at runtime if ...

One final note: the presence of "empty" @param lines (which give only the parameter name) is a clear no-go. These lines tell you nothing , but you still have to spend time reading and ignoring it . Such things are waste . Avoid this.