在记录 Java 程序时，记录类的约定是什么？ [关闭]

Question

我知道对于方法，提供了解释以及@param、@return 和@throw。但是对于类，除了对类的解释之外，还有什么特别需要包含的吗？

Answer 1

在课程级别，文档应说明：

1. 我为什么/什么时候想使用这个类？
2. 如何使用这个类（示例）
3. 这个班级如何与其他班级互动？
4. 这门课有什么意外/特别之处？ （线程安全、全局变量……）

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

Answer 2

倾向于不包括这些 cmets 或保持它们非常简短，让命名约定推动我们对类应该做什么的理解。例如，一个名为“Address”的普通 Java 对象 (POJO) 可能只需要很少的文档方式，除了使它真正独一无二的东西。浏览 GitHub 上最近的 Java 项目，您会发现情况确实如此。注释和包名也有助于从本质上描述类。

如果您更多地关注命名，则不需要记录太多 - 除了类的独特之处或它可能具有的限制。