这不是 是Java，但它正是我正在处理的事情。 另外，关注那些方法和细节，我不知道整体类文件。
在我对给定类文件的评论中，我真正需要具备哪些内容？在我的公司，我唯一可以提出的事情是：
还有其他什么应该提供吗？
我听到的一个合乎逻辑的事情是让作者不在标题之内，因为它已经通过源代码控制提供的信息是多余的。
更新 JavaDoc可以在这里假设，但是我真的更关心的是包含内容的好处的细节，是否可以挖掘的确定元数据，或者更松散，为什么等...
答案 0 :(得分：14)
我听到的一个合乎逻辑的事情就是让作者脱离标题，因为它是多余的 已经通过源代码管理提供的信息。
最后修改日期为冗余
我使用了一小组文档模式：
答案 1 :(得分：6)
否“最后修改日期” - 也属于源代码管理。
另外两个很好。基本上专注于有用的文本 - 课程的内容，关于线程安全，预期用法等的任何警告。
实施意见通常应该是关于你为什么做一些不明显的事情 - 因此应该很少见。 （例如，它可能是因为某些API以不寻常的方式运行，或者因为您可以使用有用的快捷方式，但这并不是很明显。）
答案 2 :(得分：2)
为了你自己和未来的开发者的理智，你真的应该写Javadocs。
答案 3 :(得分：2)
当您觉得需要编写注释来解释某些代码的功能时，请提高代码的可读性，以便不需要注释。您可以通过重命名方法/字段/类来实现更多meaningful names，并使用composed method pattern将更大的方法拆分为更小的方法。
即使经过所有努力，代码也不会自我解释，例如为什么必须编写一些不明显的代码的原因尚未从代码中清楚，然后是apologize by writing comments。 （有时你可以通过编写一个失败的测试来记录原因，如果有人改变了不明显但正确的代码来做明显但错误的事情。但除此之外还有一个注释也是有用的。我用这样的前缀通常使用“// HACK：”或“// XXX：”注释。）
答案 4 :(得分：0)
课程目的的总体描述，每个领域的描述和每种方法的合同。 Javadoc格式运行良好。
答案 5 :(得分：0)
如果您将组件的所有权分配给特定开发人员或团队，则应将所有者记录在组件源或VCS元数据中。