Javadoc @author tag
In Javadoc, there is an @author tag, which is supposed to indicate the original author of the file and possibly all contributors, who made significant changes to the file.
/**
* Validator used to check whether given string is
* no longer than the specified amount of characters.
*
* @author Vojtech Ruzicka
*/
public class MaxLengthValidator {
...
}You can see more details in the How to Write Doc Comments for the Javadoc Tool article and JavaDoc reference guide.
What is wrong with @author
The tag is not actually included in generated Javadoc. At least not by default - you need to explicitly specify -author parameter to include the information in the generated documentation. Therefore it is only visible to a person, who is viewing the source code. In that case, there is a much better source of information about authors and contributors - your version control system (such as Git or SVN). Adding this also in comments is a duplication of information and unwanted noise. You can already see who and when edited each and single line in the file.
Better yet, unlike the @author tag, the information is always accurate and up to date. Comments tend to rot and be outdated and obsolete quickly. Developers tend to ignore updating comments when making changes. After a while and some refactorings, the original file is usually much different than when original @author created the first version. Not to mention that developers listed are often not with the company anymore or left the project years ago.
IDE templates
What is even worse is the default, non-Javadoc template stating author and creation date, which some IDEs automatically insert into each new file. Following is the default one used by IntelliJ Idea (as of 2016.1).
/**
* Created by vojtech on 5/7/2016.
*/
public class BrandNewClass {
}It has all the disadvantages of @author Javadoc and some more. Unlike Javadoc, it is not displayed by IDE when requesting documentation pop-ups or in auto-complete. If you want to include author, use the @author tag and not those templates.
Still want to keep it?
Still not convinced? Maybe there is a company policy that requires the inclusion of the @author tag or perhaps you just love it. In that case, I suggest using it for marking a contact person, who is currently responsible for the given file. It is especially useful on large, long-running projects with many developers. While working with such a huge and old codebase, it is much more important to know who to contact regarding specific file or module rather than to know who was the major contributor years ago. Just be sure to keep the tags updated. However, with so many files to keep up to date, it may be better to include the author information on package level of whole modules rather than individual files.
CODEOWNERS
Some time ago, GitHub introduced a new concept of CODEOWNERS file.
In a nutshell, it is a file, where you can define teams or individual users responsible for various parts of the project. Note that it is not authors, but rather people who are responsible now. That is much more useful as the original author is likely to be long gone. Also, as you can define the owner on a team level, you don't have to change this all the time if there are people coming and leaving.
For GitHub, this file is used to automatically add reviewers for new pull requests, but it is also very useful just to have one place where to look for people, who can help you with certain parts of the project. This concept is not uncommon - it was originally inspired by the similar feature in Chromium.
The file uses similar patterns such as .gitignore and you can assign responsible people to each of these patterns.
# This is a comment.
# Each line is a file pattern followed by one or more owners.
# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence,
# @global-owner1 and @global-owner2 will be requested for
# review when someone opens a pull request.
* @global-owner1 @global-owner2
# Order is important; the last matching pattern takes the most
# precedence. When someone opens a pull request that only
# modifies JS files, only @js-owner and not the global
# owner(s) will be requested for a review.
*.js @js-owner
# You can also use email addresses if you prefer. They'll be
# used to look up users just like we do for commit author
# emails.
*.go docs@example.comYou can check a full-fledged example of the CODEOWNERS file here.
Even if you are not using GitHub and will not, therefore, benefit from the automatic assignment of reviewers, it may still be handy to have one centralized file where you can look up who is responsible for which part of the project.
Conclusion
I suggest you stop using the @author tag, same as Apache or Gradle did. If you keep using it, at least be sure to keep the info always up to date.
