Java源文件中的注释的最佳实践？ [英] Best Practice for comments in Java source files?

问题描述

这不是是Java，但它是我正在处理的。

还有一些是非常有用的，我真的需要在我的评论中一个给定的类文件的东西？在我的公司，我真正能够想出的唯一的事情：

• 版权/许可证

还有其他事项吗？应该提供哪些？

我听说过一个逻辑的事情是让作者离开标题，因为它与已经通过源代码控制提供的信息是多余的。 p>

更新：
JavaDoc可以在这里假设，但我真的更关心什么是包含内容，无论是可挖掘的明确元数据，还是更为宽松，WHY等...

解决方案

我听到的一个逻辑的事情是让作者不在标题中，因为它是多余的
，信息已经通过源代码控制提供。

也最后修改日期冗余

我使用一小组 em>：

• 始终记录线程安全性


• 始终记录不变性


• javadoc与示例


• 通过 WHY 和 HOW 替换已注释的元素
b $ b
• 保持评论最少

This doesn't have to be Java, but it's what I'm dealing with. Also, not so much concerned with the methods and details of those, I'm wondering about the overall class file.

What are some of the things I really need to have in my comments for a given class file? At my corporation, the only things I really can come up with:

• Copyright/License
• A description of what the class does
• A last modified date?

Is there anything else which should be provided?

One logical thing I've heard is to keep authors out of the header because it's redundant with the information already being provided via source control.

Update: JavaDoc can be assumed here, but I'm really more concerned about the details of what's good to include content-wise, whether it's definitive meta-data that can be mined, or the more loose, WHY etc...

解决方案

One logical thing I've heard is to keep authors out of the header because it's redundant with the information already being provided via source control.

also last modified date is redundant

I use a small set of documentation patterns:

• always documenting about thread-safety
• always documenting immutability
• javadoc with examples
• @Deprecation with WHY and HOW to replace the annotated element
• keeping comments at minimum

这篇关于Java源文件中的注释的最佳实践？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！