Stop using Javadoc @author tag

May 07, 2016

javadoc author tag

Are you still using @author Javadoc tag? Maybe it's time to reconsider. Let's discuss why the tag may be actually harmful and why you should stop using it.

Javadoc @author tag

In Javadoc, there is a @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.

Authors and time of changes as shown in IntelliJ Idea 2016.1

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.

Conclusion

I suggest you stop using the @author tag, same as Apacheor Gradle did. If you keep using it, at least be sure to keep the info always up to date.


Tagged with:
Vojtech Ruzicka
Written by Vojtech Ruzicka

Get notifications about new posts on Twitter, RSS or Email.