当我修改其他人时,如何修改Javadoc';s代码?

当我修改其他人时,如何修改Javadoc';s代码?,java,javadoc,Java,Javadoc,我正在处理其他人的代码并进行重大修改。(我正在将其转换为使用与他最初使用的数据库不同的数据库。)我如何在Javadoc注释中指出我不是代码的原始作者,但我确实对代码做出了贡献。是否已经有了一种干净或标准的方法?我的谷歌搜索并不能帮我解决这个问题 例如: /** * This class does some really awesome stuff. * * @author Steph the Great - Modified to use PostgreSQL instead of Derby

我正在处理其他人的代码并进行重大修改。(我正在将其转换为使用与他最初使用的数据库不同的数据库。)我如何在Javadoc注释中指出我不是代码的原始作者,但我确实对代码做出了贡献。是否已经有了一种干净或标准的方法?我的谷歌搜索并不能帮我解决这个问题

例如:

/**
* This class does some really awesome stuff.
* 
* @author Steph the Great - Modified to use PostgreSQL instead of Derby;
*         added comments to the code
*/

我也不知道原作者的名字,所以我只能写下我自己

您可以有多个
@author
标记。因此,如果您对一个类进行了大量更改,只需添加一个新的
@author
标记,其中包含您自己的名字。无需列出您所做的更改——修订历史应充分显示这一点。

这些注释不属于javadoc:-)javadoc应解释合同——它是自动生成的“文档”中提取和显示的内容。其余的只是普通的注释,或者在本例中更好的是SCM日志条目,在javadoc中没有位置

我可能会离开原作者,但如果你想获得荣誉

…请参阅javadoc参考,并注意可以多次包含它。本节内容和订购等

/**
* This class does some really awesome stuff.
* It uses PostreSQL. 
*
* @author Steph the Great
* @author Freddy Four Fingers
*/
// DEC2012 - Fred - Modified to use PostgreSQL instead of Derby (but really, use SCM!)
class Awesome { ... }
快乐编码


关于问题的注释与文章中的示例有些无关。。。如果不知道作者,那么可以做几件事。首先,也最重要的是添加一个链接或引用,指向原始来源的来源——为了清晰起见,还可以添加一个可选的“我最初没有写这篇文章”

然后,根据您的喜好:

  • 不要指定
    @author
    字段,甚至不要指定你自己。这不是必需的
  • 添加自己作为唯一作者;javadoc中提到了原始源代码
  • 添加一个虚拟作者和您自己作为第二作者,例如
    @author Unknown
    @author uncribed
    (请参阅注释和注释)
  • 在许可证条款内做任何你想做的事,如果有的话

  • 我不会太紧张。如果您觉得将您的作品与原始作者区分开来很重要,您可以使用内联注释来突出显示您的更改,或者只需在javadoc中添加注释,例如“修改为……由……完成”或其他适合您的内容。人们通常只会在有人对代码进行修改而不加评论的情况下才会对代码的修改感到不安,从而将原作者贴上了糟糕程序员的标签。只要你添加一些东西,说你已经改变了它,并且不是最初的作者,你就应该没事。在很多情况下,如果你不这样做也没关系:-)好的。我只是觉得把我的名字写下来很奇怪,因为我不知道最初写这篇文章的人的名字,也不能把他写下来。感觉上我是在为他的代码争光。@Steph:那样的话,先把
    @author unscribed
    放进去,然后再加上你自己的
    @author
    标签。“Unascribed”是作者身份未知时使用的标准名称。(JDK中的许多类,可以追溯到1.0或更早的版本,都有
    @author unascribed
    。只是为了好玩,谷歌搜索“author unascribed”。-)好的,太好了。非常感谢!另一个问题是我不认识原作者,因为他没有在代码中写任何注释。不过,如果把我的名字单独列为作者的话,我会觉得很奇怪,因为这看起来像是我拿走了他的全部功劳。你认为我应该省略我自己的名字而不列出作者吗?我无法决定最好的方法是什么。+1表示“那些评论不属于javadoc”。我无情地删除了代码库中的
    @author
    标记:它们不会增加任何超出我们在源代码控制系统中已有的值,而且一旦过时,它们实际上就具有负值。@Chris Jester Young:不,这就是svn(或您首选的SCM中的等效名称)的作用。@pst:(重新编辑)。当作者身份未知时,标准占位符名称为“未指定”。有关详细信息,请参阅。@Steph:如果您不知道原始作者,您如何知道您可以编辑代码?你应该知道,不表明作者身份并不等同于公共领域。