我想知道创建Javadoc时的最佳实践。我有一个包含许多文件的项目。许多开发人员已经创建了代码。每个文件都有一个注释@author
,因此很明显是谁创建了一个特定的类。
但是,当其他开发人员向文件添加新代码、修改它等时,他应该如何通知团队的其他成员他已经创建了一些新函数或修改了现有代码?换句话说,我们应该如何“保持Javadoc与现实的兼容性”?;)
@author
标签中?这样,如果有任何疑问,就更容易确定该问谁了。@author
标记。?当然,因为我们使用SVN,所以很容易调查谁做了什么,但为了保持清晰,也应该考虑Javadoc的东西。
使用这些@author
标记的最佳方式是什么?
发布于 2013-06-24 16:49:44
我要说的是,在大多数情况下,@author
是不受欢迎的噪音。API的用户不应该--可能也不会--关心或想知道是谁写了哪些部分。
而且,正如您已经说过的,SVN已经以比代码更具权威性的方式持有这些信息。因此,如果我是团队中的一员,我总是更喜欢SVN的日志,而忽略@author
。我敢打赌,无论你采取什么策略,代码都会与现实脱节。遵循不要重复自己的原则,为什么要把这些信息放在两个地方呢?
但是,如果出于某种官僚或政策原因,必须将此信息包含在代码中,您是否考虑过在签入时自动更新代码中的@author
标记?您可能可以使用SVN钩子来实现这一点。例如,您可以列出所有按更改顺序更改给定文件的开发人员;或者更改最多的开发人员;等等。或者,如果在您向外界发布的(源代码)代码中强制使用@author
,您可以考虑将@author
自动添加为发布构建的一部分(我怀疑您可以通过某种方式从SVN获得此信息)。
至于添加多个类级别的@author
标记(或其他注释),我会说你会积累很多无用的噪音。(同样,您有SVN。)
在我的经验中,识别历史变更(例如,对一行代码或方法的变更),然后找出这与哪个变更集相关(以及哪个跟踪票)要有用得多。然后您就有了变更的完整上下文:您有票证、变更集,您可以在同一票证上找到其他变更集,或者大约在同一时间,您可以找到相关的票证,您可以看到形成该工作单元的所有变更。你永远不会从代码中的注解或注释中得到它。
发布于 2013-06-24 15:19:08
您可能需要考虑为什么要在源代码中使用author标签。阿帕奇基金会不这么认为,我也同意。
http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags
据我所知,这是一种货物狂热的工作方式,从原始资料打印在纸上开始。使用现代版本控制系统,这些信息和更多信息都可以在历史中找到。
发布于 2013-06-24 15:15:07
您可以有多个@author
标记。如果你对一个类做了一些大的修改,只需添加一个带有你自己名字的新@author
标签。没有必要标记您所做的更改,也不需要在更改的周围加上您的名字,因为修订历史应该能够清楚地显示出来。
https://stackoverflow.com/questions/17269843
复制相似问题