Javadoc @author tag good practices

Question

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 @author, 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"? ;)

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

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 @author tags?

Answer 1

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:

• Most widespread software or organisation projects are developed by multiple authors, not individuals anymore.
• Majority of software is versioned in Git, CI/CD and cloud is reachable reality.
• Advanced IDEs visualise greatly code changes. Code changes are more important than the overall class source code.
• Handling bugs caused by code changes are far more important than handling bugs caused by the usage of the wrong class version.
• Unless the software is a library, IP/commercial software, framework with regular releases, authorship has no meaning.
• It is highly probable that the authors of the source code you use/work on are not working or never work in your organisation.
• Maintaining an appropriate ratio of author contribution in author declaration leads to additional effort with 0 gain. Nobody wants that.

Therefore, knowledge of simple code edits and appropriate line changes are more important than knowledge of the whole class.

Here is my opinion on class authorship digested to the short article.

Answer 2

Building off of this answer and digging through links from posts from 2004 I found this (pasted below). It's from Dirk-Willem van Gulik who was one of the founders of the Apache Software Foundation so I assume he had some input on the decision to stop using @author tags.

List:       xml-cocoon-dev Subject:    Re: @author tags (WAS: RE: ASF
Board Summary for February 18, 2004) From:       Dirk-Willem van Gulik
<dirkx () asemantics ! com> Date:       2004-02-27 10:33:32
Message-ID: 63E38432-6910-11D8-BA7E-000A95CDA38A () asemantics ! com

On Feb 27, 2004, at 12:45 AM, Conal Tuohy wrote:

I don't think the ASF should discourage developers from keeping useful metadata about the code inside the source files. What better place to put the metadata than in the code? This makes it more likely to be used and kept up to date than if it was stored somewhere else, IMHO.

One way to look at this is that @author tags are in a way factually 'wrong'; in most cases it just signals which person wrote the first skeleton of that code; but subsequently it was fixes, peer-reviewed and looked at by a whole community. Also do not forget the many people in your community which help with QA, Documentation, user-feedback and so on. To put one person in the (hot) seat for what is essentially a group effort is not quite right.

Looking through the CVS logs of a few tomcat files: each block of 30 lines seems to have had commits of at least 5 persons; with a median of 6 and an average of 9. The average number of @author tags on those arbitrary blocks is about 0.5. And that is not counting QA, docs, suggestions of mailing lists, bug resolutions, user support. I.e. those things which make tomcat such a great supported product.

Secondly what we 'sell' as the ASF brand is a code base which is peer reviewed, quality controlled and created by a sustainable group which will survive the coming and going of volunteers. One where knowledge is generally shared and not just depended on one single individual. This is one of the key reasons why large companies, governments, etc have a lot less qualms about using apache than using most other open source; we mitigate the worry that it depends on a single person, and can implode or fork without warning, right from the get-go.

Finally - a lot of developers do live in countries where you can get sued. The ASF can provide a certain level of protection; but this is based on the KEY premisse that there is oversight and peer review. That what we ship is a community product; and that everything is backed by the community and cannot be attributed to a single person. Every commit gets peer review; ever release requires +1s' and are backed by the community as a whole. @author tags are by necessity incomplete and thus portrait the situation inaccurately. Any hint or suggestion that parts of the code are not a community product makes defence more complex and expensive. We do not want to temp anyone - but rather present a clean picture with no blemishes or easy go's.

And to give this a positive slant; be -proud- of this culture; be proud of being part of something larger of incredible quality. Each of you did not just write a few pesky lines of code surrounded by an @author tag; but where instrumental in getting the -whole- thing work ! And if you are ever trying to understand why cocoon made it this far, and other commercial/open-source projects did not, then do look there; quality and a sense of long term stability.

Take Care, Have fun,

Dw

While tracking this down I came across a few blog posts against this and some in favor. That's a very small sample size but I think it is fair to say this was at least a controversial change -- some folks wanted them to stay. That said, in 2022 I don't really ever see them used. (Remember, this mail is from 2004.) You even mentioned it yourself about SVN history (but now maybe Git is the more common tool) and even in this mail they mention the CVS logs (another source control tool). Maybe the source control tools of today are easier to use, who knows.

I feel like there still might be some oddball use cases that make sense but I don't think the standard idea of "I wrote (or modified) this so I'm putting myself as the @author" is necessary. I currently have a question on Code Review about using it for Creative Commons attribution and (in my opinion) I think it's a good use but I would hardly call that a well-accepted good practice (but I don't think it hurts).

Answer 3

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

https://web.archive.org/web/20150226035235/www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

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.

Answer 4

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.

Answer 5

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.

Answer 6

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 adding it to a stamp on a piece of metal in a computer helped design. 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.

Answer 7

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 (See this question for more detail).

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

Answer 8

I would say that for most purposes @author 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 @author. 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 @author 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 @author is mandated in (source) code you release to the outside world, you could consider adding the @author 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 @author 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.

Answer 9

You can have more than one @author tag. In case you make some big changes to a class, just add a new @author 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.