blocks|key|187515|text|您可以有多个@author标记。如果你对一个类做了一些大的修改，只需添加一个带有你自己名字的新@author标签。没有必要标记您所做的更改，也不需要在更改的周围加上您的名字，因为修订历史应该能够清楚地显示出来。|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|187516|entityMap^0|6|7|1B|7|0^^$0|@$1|2|3|4|5|6|7|H|8|@$9|I|A|J|B|C]|$9|K|A|L|B|C]]|D|@]|E|$]]|$1|F|3|-4|5|6|7|M|8|@]|D|@]|E|$]]]|G|$]]

You can have more than one <code>@author</code> tag. In case you make some big changes to a class, just add a new <code>@author</code> tag with your own name in it. There's no need to mark the changes you've done or to put your name around the changes, as the revision history should be able to display that clearly.

blocks|key|3013737|text|您可能需要考虑为什么要在源代码中使用author标签。阿帕奇基金会不这么认为，我也同意。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|3013738|http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags|offset|length|3013739|据我所知，这是一种货物狂热的工作方式，从原始资料打印在纸上开始。使用现代版本控制系统，这些信息和更多信息都可以在历史中找到。|3013740|entityMap|0|LINK|mutability|MUTABLE|url^0|0|0|2J|0|0|0^^$0|@$1|2|3|4|5|6|7|O|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|P|8|@]|9|@$D|Q|E|R|1|S]]|A|$]]|$1|F|3|G|5|6|7|T|8|@]|9|@]|A|$]]|$1|H|3|-4|5|6|7|U|8|@]|9|@]|A|$]]]|I|$J|$5|K|L|M|A|$N|C]]]]

You may want to consider why you want author tags in the source. The Apache Foundation do not and I agree.

<a href="http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags" rel="noreferrer">http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags</a>

To my best understanding this is a cargo cult way of working from when sources were printed on paper. With modern version control systems this information and more can be found in the history anyway.

blocks|key|185465|text|我要说的是，在大多数情况下，@author是不受欢迎的噪音。API的用户不应该--可能也不会--关心或想知道是谁写了哪些部分。|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|185466|而且，正如您已经说过的，SVN已经以比代码更具权威性的方式持有这些信息。因此，如果我是团队中的一员，我总是更喜欢SVN的日志，而忽略@author。我敢打赌，无论你采取什么策略，代码都会与现实脱节。遵循不要重复自己的原则，为什么要把这些信息放在两个地方呢？|185467|但是，如果出于某种官僚或政策原因，必须将此信息包含在代码中，您是否考虑过在签入时自动更新代码中的@author标记？您可能可以使用SVN钩子来实现这一点。例如，您可以列出所有按更改顺序更改给定文件的开发人员；或者更改最多的开发人员；等等。或者，如果在您向外界发布的(源代码)代码中强制使用@author，您可以考虑将@author自动添加为发布构建的一部分(我怀疑您可以通过某种方式从SVN获得此信息)。|185468|至于添加多个类级别的@author标记(或其他注释)，我会说你会积累很多无用的噪音。(同样，您有SVN。)|185469|在我的经验中，识别历史变更(例如，对一行代码或方法的变更)，然后找出这与哪个变更集相关(以及哪个跟踪票)要有用得多。然后您就有了变更的完整上下文:您有票证、变更集，您可以在同一票证上找到其他变更集，或者大约在同一时间，您可以找到相关的票证，您可以看到形成该工作单元的所有变更。你永远不会从代码中的注解或注释中得到它。|185470|entityMap^0|E|7|0|1U|7|0|1C|7|40|7|4E|7|0|A|7|0|0^^$0|@$1|2|3|4|5|6|7|P|8|@$9|Q|A|R|B|C]]|D|@]|E|$]]|$1|F|3|G|5|6|7|S|8|@$9|T|A|U|B|C]]|D|@]|E|$]]|$1|H|3|I|5|6|7|V|8|@$9|W|A|X|B|C]|$9|Y|A|Z|B|C]|$9|10|A|11|B|C]]|D|@]|E|$]]|$1|J|3|K|5|6|7|12|8|@$9|13|A|14|B|C]]|D|@]|E|$]]|$1|L|3|M|5|6|7|15|8|@]|D|@]|E|$]]|$1|N|3|-4|5|6|7|16|8|@]|D|@]|E|$]]]|O|$]]

I would say that for most purposes <code>@author</code> is unwanted noise. The user of your API shouldn't - and probably doesn't - care, or want to know, who wrote which parts.

And, as you have already stated, SVN already holds this information in a much more authoritative way than the code can. So if I was one of the team, I would always prefer SVN's log and ignore the <code>@author</code>. I'd bet that the code will get out of sync with reality, whatever policy you adopted. Following the Don't Repeat Yourself principle, why hold this information in two places?

If, however, there is some bureaucratic or policy reason that this information MUST be included in the code, have you considered automatically updating the <code>@author</code> tag in the code on check in? You could probably achieve this with an SVN hook. You could for example list all the developers who changed a given file in the order they changed it; or who changed it most; or whatever. Or, if the <code>@author</code> is mandated in (source) code you release to the outside world, you could consider adding the <code>@author</code> automatically as part of the release build (I suspect you could get this information out of SVN somehow).

As for adding more than a single class level <code>@author</code> tag (or other comment), I'd say you'd be accumulating a lot of unhelpful noise. (Again, you have SVN.)

In my experience it is much more useful to identify a historical change (say a change to a line of code, or a method), then to work out which change set this relates to (and which track ticket). Then you have the full context for the change: you have the ticket, the change set, you can find other change sets on the same ticket, or around the same time, you can find related tickets, and you can see ALL the changes that formed that unit of work. You are never going to get this from annotation or comments in code.

blocks|key|2801568|text|在有很多开发人员的大型且长期运行的项目中，知道ho负责给定的代码，谁可以为您提供额外的信息等等，这是很有用的。在这种情况下，使用@author标签在文件中包含这样的信息会很方便。没有标记谁创建了文件或谁做出了一些重大贡献，但谁是该代码的联系人。这些人可能是非常不同的人，因为原始作者可能已经在不同的项目中，或者几年前就离开了公司。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|2801569|我认为在大型项目中，这种方法可能很方便，但有一个警告。保存每个文件的作者信息是非常困难的，因为有大量的文件，迟早会失败。越来越多的文件将包含过时的信息，开发人员将不再信任这个@author作为信息源，并将其忽略。|2801570|可能有效的解决方案是，不是在每个文件上都保持@author，而是只对每个模块(高级包)保持@author。Javadoc有一个特性，你不仅可以记录文件，还可以记录整个包(See+this+question+for+more+detail)。|offset|length|2801571|然而，这是一个特例，只要你的项目不是那么大或太老，我建议省略作者信息。|2801572|entityMap|0|LINK|mutability|MUTABLE|url|https://stackoverflow.com/q/624422/4560142^0|0|0|2D|X|0|0|0^^$0|@$1|2|3|4|5|6|7|R|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|S|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|T|8|@]|9|@$F|U|G|V|1|W]]|A|$]]|$1|H|3|I|5|6|7|X|8|@]|9|@]|A|$]]|$1|J|3|-4|5|6|7|Y|8|@]|9|@]|A|$]]]|K|$L|$5|M|N|O|A|$P|Q]]]]

In really big and long-running projects with lots of developers, it is useful to know ho is responsible for given code, who can provide you with extra information and such. In that case it would be handy to have such an informationin the file using @author tag. Not marking who created the file or who made some major contributions, but who is a contact person for that code. Those might be very different people as original author may be already on different project or left the company years ago.

I think on huge project that approach may be handy, however there is a caveat. Keeping every single file's author information is very difficult as there is huge amount of files and sooner or later will fail. More and more files will have outdated information and developers will no longer trust this @author as source of information and will just ignore it.

Solution, which may work, is not to keep @author on every single file, but only per module (high level packages). Javadoc has a feature, where you can document not only files but whole packages (<a href="https://stackoverflow.com/q/624422/4560142">See this question for more detail</a>).

This is however a special case and as long as your project is not that big or old, I reccomend ommiting the author information.

blocks|key|3013940|text|我完全同意这是不必要的，你可能不应该添加它。然而，我仍然添加它，我认为它就像在一幅画上添加签名，或adding+it+to+a+stamp+on+a+piece+of+metal+in+a+computer+helped+design。你写了这段代码，加上你的名字表明你对它感到自豪，你对它的质量充满信心，即使它没有其他作用。即使在将来它被改变了，你也为构建在它之上的一切奠定了基础，如果它真的被完全重写了，那么这个标签就可以被改变、移除或扩展。我同意它是多余的，这要归功于版本控制，但让你的名字出现在版本控制中并不是那么令人满意。如果有人只是添加“最终”或格式化代码，他们的名字将在版本控制中，即使他们几乎没有贡献。我也同意它是噪声，因为它不会给代码增加任何东西，然而它真的甚至有一点明显的恼人吗？我不这样认为。如果你是理性的，我认为它可以使一个项目变得“更友好”，如果这是有意义的。|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|3013941|entityMap|0|LINK|mutability|MUTABLE|url|https://www.cultofmac.com/122408/signed-by-steve-jobs-co-signatures-inside-the-original-macintosh-case/^0|1D|1W|0|0^^$0|@$1|2|3|4|5|6|7|L|8|@]|9|@$A|M|B|N|1|O]]|C|$]]|$1|D|3|-4|5|6|7|P|8|@]|9|@]|C|$]]]|E|$F|$5|G|H|I|C|$J|K]]]]

I completely agree that it is unnecessary and you probably shouldn't add it. However I still add it, I see it like adding a signature to a painting, or <a href="https://www.cultofmac.com/122408/signed-by-steve-jobs-co-signatures-inside-the-original-macintosh-case/" rel="noreferrer">adding it to a stamp on a piece of metal in a computer helped design</a>. You wrote that piece of code, and adding your name shows that you are proud of it and that you are confident of its quality, even if it does nothing else. Even if it's changed in the future, you laid the foundations for everything built on top of it, and should it really be rewritten completely, the tag can be changed, removed or expanded. I agree that it is redundant thanks to version control, but having your name in version control isn't nearly as satisfying. If someone just adds a "final" or formats the code, their name will be in version control, even if they hardly contributed at all. I also agree that it is noise, in that it doesn't add anything to the code, however is it really even slightly noticeably annoying? I don't think so. If you are reasonable about it, I think it can make a project "more friendly", if that makes sense.

blocks|key|187647|text|拥有@author标签和多个作者是非常方便的。即使是Oracle的文档也概述了将@author放在类的顶部是一种很好的实践，以便向完成这项工作的特定作者表示信任，并在开发过程中需要与某人交谈时跟踪事件。如果有多个作者，则可以按照他们在特定java文件/类上的贡献顺序列出他们。是的，有插件，使用git结构，你可以查看代码中的作者名字，但是这个想法是有争议的。因为，有时多个作者编辑同一行代码，并且可能不会显示两个作者编辑同一行代码。我有插件启用，它从来不会显示编辑同一行代码的两个作者的名字。对于大公司来说，建立这种实践是很方便的。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|187648|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

It's very handy to have @author tag and have multiple authors. Even Oracle's Documentation outlines that it's good practice to have @author on top of class to give credit to particular author who did the job and also to track down things if someone needs to be spoken to during development process. If there are multiple authors they can be listed in order they contributed on a particular java file/class. Yes, there are plugins and with git structure, you can check can see author's name hanging around in the code precisely, but this idea will be controversial though. Because, sometimes multiple authors edit same line of code and might not show two authors editing same line of code. I have plugin enabled, it never shows 2 authors name for editing same line of code. With big companies, it's handy to have this practice set up.

blocks|key|185538|text|如果是公司代码，我不会这么做:我们有VCS。相反，如果这是一篇博客文章或我个人存储库的代码片段，我会自豪地添加这一点，并希望一些复制粘贴的人会发现我的代码很有用，并意外地复制了我的名字:)|type|unstyled|depth|inlineStyleRanges|entityRanges|data|185539|我想，这是我喜欢的类型。|185540|entityMap^0|0|0^^$0|@$1|2|3|4|5|6|7|F|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|G|8|@]|9|@]|A|$]]|$1|D|3|-4|5|6|7|H|8|@]|9|@]|A|$]]]|E|$]]

If it is company code, I would not do that: we have VCS. Instead, if it is a blog post or code snippets of my personal repo, I would proudly add this and hoping some copy-paste guy will find my code useful and accidentally, copy my name as well :)

Just my type of humour, I guess.

blocks|key|183322|text|这是2021年，当我回答这个问题时，距离第一次发表已经近8年了。这个世界有点不同，它正在全速使用微服务。因此，我将围绕作者身份的整体情绪总结如下：，它是毫无意义的。让我在几点上解释一下：|type|unstyled|depth|inlineStyleRanges|offset|length|style|BOLD|entityRanges|data|183323|大多数分布广泛的软件或组织项目都是由多个作者开发的，而不是由个人开发的。anymore.|183324|Majority+of+software的版本是在Git、CI/CD和cloud+is+reachable+reality.|unordered-list-item|183325|
|183326|Advanced+|183327|中实现的，IDE可视化了大量代码更改。代码更改比整个类源代码更重要。|183328|处理由代码更改导致的错误比处理由于使用错误的类而导致的错误要重要得多。软件是一个库、IP/商业软件、定期发布的框架，作者身份没有任何意义。|183329|很可能您使用的源代码的作者没有工作或从未在您的代码中工作过。在作者声明中，适当的作者贡献比例会导致额外的工作，但收益为0。没有人想要那样。|183330|183331|183332|因此，简单的代码编辑和适当的行更改知识比整个类的知识更重要。|183333|这是我对class+authorship+digested+to+the+short+article的看法。|183334|entityMap|0|LINK|mutability|MUTABLE|url|https://codekopf.com/opinion/removing-class-authorship-considered-as-code-cruft-and-completely-redundant/^0|21|8|0|0|0|0|0|0|0|0|0|0|0|4|1A|0|0^^$0|@$1|2|3|4|5|6|7|18|8|@$9|19|A|1A|B|C]]|D|@]|E|$]]|$1|F|3|G|5|6|7|1B|8|@]|D|@]|E|$]]|$1|H|3|I|5|J|7|1C|8|@]|D|@]|E|$]]|$1|K|3|L|5|6|7|1D|8|@]|D|@]|E|$]]|$1|M|3|N|5|J|7|1E|8|@]|D|@]|E|$]]|$1|O|3|P|5|J|7|1F|8|@]|D|@]|E|$]]|$1|Q|3|R|5|J|7|1G|8|@]|D|@]|E|$]]|$1|S|3|T|5|J|7|1H|8|@]|D|@]|E|$]]|$1|U|3|-4|5|6|7|1I|8|@]|D|@]|E|$]]|$1|V|3|-4|5|6|7|1J|8|@]|D|@]|E|$]]|$1|W|3|X|5|6|7|1K|8|@]|D|@]|E|$]]|$1|Y|3|Z|5|6|7|1L|8|@]|D|@$9|1M|A|1N|1|1O]]|E|$]]|$1|10|3|-4|5|6|7|1P|8|@]|D|@]|E|$]]]|11|$12|$5|13|14|15|E|$16|17]]]]

It is the year 2021 and When I am replying to this question it is nearly 8 years from the first publish. The world is a little bit different place and it is using microservices at full throttle. Therefore I would sum up the overall mood around authorship like this: it is pointless. Let me explain it on a few points:
<ul>
<li>Most widespread software or organisation projects are developed by multiple authors, not individuals anymore.</li>
<li>Majority of software is versioned in Git, CI/CD and cloud is reachable reality.</li>
<li>Advanced IDEs visualise greatly code changes. Code changes are more important than the overall class source code.</li>
<li>Handling bugs caused by code changes are far more important than handling bugs caused by the usage of the wrong class version.</li>
<li>Unless the software is a library, IP/commercial software, framework with regular releases, authorship has no meaning.</li>
<li>It is highly probable that the authors of the source code you use/work on are not working or never work in your organisation.</li>
<li>Maintaining an appropriate ratio of author contribution in author declaration leads to additional effort with 0 gain. Nobody want that.</li>
</ul>
Therefore knowledge of simple code edits and appropriate line changes are more important than knowledge of the whole class.
Here is my opinion on <a href="https://codekopf.com/opinion/removing-class-authorship-considered-as-code-cruft-and-completely-redundant/" rel="nofollow noreferrer">class authorship digested to the short article</a>.

I'm wondering about best practices when creating Javadocs. I have a project with many files. Code has been created by many developers. Each file has an annotation <code>@author</code>, so it is obvious who has created a particular class. 

But when some other developer adds new code to a file, modifies it, etc., how should he inform the rest of the team that he has created some new function or has modified existing code? In other words, how should we "keep the Javadocs compatible with reality"? ;)

<ul>
<li>Add his name to the existing <code>@author</code> tag? Then, it is easier to identify who to ask in case of any doubts.</li>
<li>Add an <code>@author</code> tag to each new method, inner class, etc.?</li>
</ul>

Of course, since we use SVN, it is easy to investigate who has made what, but for keeping things clear this Javadoc stuff should be taken into consideration as well.

What's the best way to use these <code>@author</code> tags?

Javadoc @author tag good practices

版本控制系统

我想知道创建Javadoc时的最佳实践。我有一个包含许多文件的项目。许多开发人员已经创建了代码。每个文件都有一个注释@author，因此很明显是谁创建了一个特定的类。但是，当其他开发人员向文件添加新代码、修改它等时，他应该如何通知团队的其他成员他已经创建了一些新函数或修改了现有代码？换句话说，我们应该如何“保持Java...

问Javadoc @author标签良好实践
EN

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问Javadoc @author标签良好实践EN

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问Javadoc @author标签良好实践
EN