Question

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

是应该记录每一个java方法还是只公开其他类使用的方法？

像这样

Intent emailIntent = new Intent(android.content.Intent.ACTION_SEND);
emailIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
emailIntent.setType("plain/text");
emailIntent.setClassName("com.google.android.gm", "com.google.android.gm.ComposeActivityGmail");
emailIntent.putExtra(android.content.Intent.EXTRA_EMAIL, new String[]{"someone@gmail.com"});
emailIntent.putExtra(android.content.Intent.EXTRA_SUBJECT, "Yo");
emailIntent.putExtra(android.content.Intent.EXTRA_TEXT, "Hi");
startActivity(emailIntent);

Answer 1

这取决于您的工作场所/团队的惯例/ ......

但是作为经验法则：记录公共API是最小的。如果私有方法真的很神秘 - 记录这个方法的作用可以在以后安全很多。

所以你应该总是问问自己：

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

应该将java doc放在每个java方法上吗？

1 个答案: