CODEWITHSUNDEEP
javajavadoc
degath
degath

Reputation: 1621

Performing javadoc comments

I'm reading a lot of articles about javadoc, but still can't menage when the "boilerplate" 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 perform them somehow to be less boilerplate or I should just remove them?

Why in 75% of articles called "best practices for Javadoc we have repetitions? 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);

Isn't it writing 2 times same thing?

Upvotes: 5

Views: 259

Answers (1)

GhostCat
GhostCat

Reputation: 140613

To a certain degree, this is about "style". Nonetheless, let's have a look:

/**
 * 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 a certain merit in having

  • a human readable description that tells you what a method does
  • additional information using the @param / @return tags

You could for example rewrite this like:

/**
 * 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 room to use the additional tags to provide actually different information: each line in my version serves a certain purpose, whereas your example just repeats the same information, albeit using slightly different wording.

But as said, in the end, this is a matter of style, and the key point is: you should pick that "style" that you (and your peers) find to be the most helpful for your context.

And please note: instead of repeating "obvious" things over and over again, a more helpful comment could rather look 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 - to go with a single @return line. But instead mention crucial aspects such as - this method is throwing that runtime exception if ...

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

Upvotes: 8

Related Questions