java 文档应该在每个 java 方法上吗

Question

我在 n 层应用程序中有一个服务 Class，我正在尝试 java-doc 这个 class，其中一些方法是 public 和@Transactional 和其他是私有的，仅供 class 使用，

是否应该记录每个 java 方法，还是仅记录 public 供其他 class 使用的方法？

像这样

/**
* 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

这取决于您的 workplace/team/...

但根据经验：记录 public API 是最低要求。如果一个私有方法真的很神秘 - 记录这个方法的作用可以在以后节省很多时间。

所以你应该经常问自己：

我能在 5 年后的合理时间内理解这段代码吗？如果您的回答是否定的，那么请考虑让代码不那么神秘并记录下来。这包括私有方法，但也包括私有方法 constants/fields（例如幻数 - 它们现在可能有意义，但以后也会有意义吗？）

java 文档应该在每个 java 方法上吗

should the java doc be on every single java method

javadoc