should the java doc be on every single java method

Question

I have a Service Class in an n-tier application , I am trying to java-doc this class, some of these methods are public and @Transactional and others are private for the class use only ,

Should every single java method be documented or just the methods that are public for other classes to use ?

like this

/**
* Updates an existing Strategy plan with new values, this Strategy plan can't be approved to allow update
* @param planId old Strategy plan ID
* @param plan new Strategy plan instance 
* @param levelId level of Strategy plan that is 1 for Company plan , 2 for Department plan
*/

@Override
@Transactional
public void updatePlan(Integer oldPlanId, Plan plan, Integer levelId) {
... 
}


private void updatePlanDate(Plan oldPlan, Plan newPlan, Integer levelId) {
...
}

}

Answer 1

That depends on the conventions of your workplace/team/...

But as rule of the thumb: documenting the public API is the minimum. If a private method is really cryptic - documenting what this method does could safe a lot of time later.

So you should always ask yourself:

Will I be able to understand this code in a reasonable time 5 years later? If your answer is no, then think about making the code less cryptic and document it. This includes private methods but also private constants/fields (for example magic numbers - they may make sense now, but will they make sense later too?)