记录Java程序时，记录类的惯例是什么？

Question

我知道对于方法，提供了解释，@ param，@ return和@throw。但是对于课程，除了课程的解释之外，还有什么特别的东西需要包括在内吗？

Answer 1

在课程级别，文档应该解释：

1. 为什么/何时我想使用这个课程？
2. 我如何使用此课程（示例）
3. 这个班级如何与其他班级一起玩？
4. 这堂课的意外/特别之处是什么？ （线程安全，全局变量，......）

总而言之，类文档应该提供更广泛的视图，展示类如何适应其余代码。

Answer 2

趋势是不要包含这些注释或保持简短，并让命名约定驱动我们理解类应该做什么。例如，一个名为＆＃34; Address＆＃34;的普通Java对象（PO​​JO）;可能需要很少的文档，除了使它真正独特的东西。看看GitHub上最近的Java项目，你会发现这种情况。注释和包名称本身也有助于描述该类。

如果您更专注于命名，那么您不应该记录太多 - 除了使该类具有独特性或限制之外的其他内容。