Uri*_*Uri 62
对于仅实现的方法(不是覆盖),确定,为什么不,特别是如果它们是公共的.
如果你有一个压倒一切的情况,并且你要复制任何文本,那么绝对不会.复制是造成差异的绝佳方式.因此,用户可以根据他们是否检查超类型或子类型中的方法,对您的方法有不同的理解.使用@inheritDoc或不提供文档 - IDE将在Javadoc视图中使用最低的可用文本.
顺便说一句,如果你的重写版本在超类型的文档中添加了东西,那么你可能会遇到麻烦.我在博士期间研究了这个问题,发现如果他们通过超类型调用,一般人们永远不会知道覆盖版本中的额外信息.
解决这个问题是我构建的原型工具的一个主要特征 - 每当你调用一个方法时,你都会看到它的目标或任何潜在的重写目标是否包含重要信息(例如,冲突的行为).例如,在调用put on map时,系统会提醒您,如果您的实现是TreeMap,则您的元素需要具有可比性.
Sjo*_*erd 24
实现和接口都应该有javadoc.使用某些工具,您可以使用@inheritDoc关键字继承接口的文档.
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }
Van*_*nya 20
一些好的做法是放
/**
* {@inheritDoc}
*/
作为实现的javadoc(除非有关于实现细节的额外解释).
Nat*_*tix 16
通常,当您重写方法时,您遵守基类/接口中定义的协定,因此您无论如何都不想更改原始的javadoc.因此,不需要在其他答案中提及的@inheritDoc或@see标记的使用,并且实际上仅在代码中用作噪声.按规定所有明智的工具继承父类或接口方法的javadoc 这里:
Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:
- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface
事实上,一些工具(我正在看着你,Eclipse!)默认情况下在覆盖方法时生成这些只是一种令人悲伤的状态,但并不能证明用无用的噪音混淆你的代码.
当然可能存在相反的情况,当你真的想要为重写方法添加注释时(通常是一些额外的实现细节或使合同更严格).但在这种情况下,你几乎不想做这样的事情:
/**
* {@inheritDoc}
*
* This implementation is very, very slow when b equals 3.
*/
为什么？因为继承的评论可能很长.在这种情况下,谁会注意到3段长段末尾的额外句子？相反,只需写下你自己的评论,这就是全部.所有javadoc工具总是显示某种指定的链接,您可以单击该链接来读取基类注释.将它们混合没有意义.
@see它生成一个指向界面中描述的链接.但我认为添加一些有关实现的细节也是很好的.
Sjoerd 正确地说接口和实现都应该有 JavaDoc。接口 JavaDoc 应该定义方法的契约 - 方法应该做什么、需要什么输入、应该返回什么值以及出现错误时应该做什么。
实施文件应注明合同的扩展或限制，以及实施的适当细节，尤其是绩效。