我修改其他人的代码时如何修改Javadoc？

我正在处理别人的代码并进行重大修改。（我将它转换为使用与原来使用的数据库不同的数据库。）我如何在Javadoc注释中指出我不是代码的原始作者，但是我确实为它做出了贡献。是否有干净的或标准的方式来做到这一点？我的谷歌搜索不帮我弄清楚这一点。我修改其他人的代码时如何修改Javadoc？

例子：

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

我也不知道原作者的名字，所以我只能放下就是我自己。。。

来源

2011-06-17 Steph

我不会太过紧张。如果您认为将工作与原作者区分开很重要，您可以使用内嵌评论来突出显示您的更改，或者只是向javadoc添加评论，例如“修改要......”或任何套件。人们通常只会对代码的变化感到不安，如果有人发生了变化并且没有发表评论，从而将原作者标记为糟糕的程序员。只要你添加一些东西说你已经改变了它，而不是原作者，你应该没问题。而且在很多情况下，如果你不这样做： - ） – drekka 2011-06-17 00:12:51

那些注释不属于javadoc :-) javadoc应解释合同 - 它是在自动生成的“文档”中提取和显示的内容。其余的只是普通的注释，或者在这种情况下可能更好，SCM日志条目并且在javadoc中没有位置！

我很可能只是离开原作者，但如果你想贷款...

...看到@author的Javadoc参考，并请注意，它可以包含多次。本部分explicitly relates to multiple authors及订购等

/** 
* 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 unascribed（见评论和@author）。
根据许可证的规定做任何你想要的，如果有的话。

来源

2011-06-17 00:14:05

那么，另一个问题是我不知道原作者，因为他没有在他的代码中写一个单独的评论。不过，仅仅把我的名字作为作者，我会觉得很奇怪，因为它看起来像我正在全力以赴。你认为我应该省略自己的名字，没有列出作者吗？我无法决定最好的方法会在这里。 – Steph 2011-06-17 00:21:22

+1“这些评论不属于javadoc。”我无情地删除了我们代码库中的@ @ author'标记：它们不会增加我们的源代码管理系统中已有的任何值，并且只要它们过期，它们实际上就具有* negative *值。 – 2011-06-17 00:27:18

@Daniel：如果有关于代码的“问题”，那么'@ author'标签可以很好地确定责任人。 ;-) – 2011-06-17 00:28:10

您可以有多个@author标签。因此，如果您对课程进行了大量更改，只需添加一个新的@author标签，并在其中添加自己的名称。没有必要列出您所做的更改 - 修订历史记录应该显示得足够好。

来源

2011-06-17 00:12:30

好的。作为作者，我感到很奇怪，因为我不知道这个人的名字是谁原来写的，不能让他失望。这感觉就像我为他的代码获得功劳。 – Steph 2011-06-17 00:16:18

@Steph：在这种情况下，请先将'@author unascribed'，然后添加您自己的'@ author'标签。 “未分类”是作者身份未知时使用的标准名称。（JDK中的很多类可以追溯到1.0或更早的版本，其中'@ author未被描述“。仅仅为了好玩，谷歌因为”author unascribed“。:-)） – 2011-06-17 00:24:49

好吧，太好了。非常感谢！ – Steph 2011-06-17 00:31:12

我修改其他人的代码时如何修改Javadoc？

回答

相关问题