Does source code management make Javadoc's @author and @since redundant?

Question

In most teams there is a rule that says that the @author and @since keywords have to be used for all documented classes, sometimes even methods.

In an attempt to focus on what matters, I don't use these keywords and instead rely on the fact that I can use the source control management system to determine who the author of a class is and since when it exists.

I believe that @author and @since come from a time where version control was not yet common and I think that they are rather redundant by now. How do you think about this? Should modern Java projects use them?

Answer 1

I know that we have used them, and they are really nice when simply perusing the source code. I have had more than one situation where the @since has been really handy to have in there, as it would have taken a bit of work to determine what version something was added in (by comparing dates, etc).

Just my experience however. I think the @author has been less useful, but since we can autogenerate both pieces of data when creating new classes, it doesn't seem like a waste to just let the system do it to me.

Answer 2

I think documentation rules should be enforced only if you need them. If it's redundant for you to put those in Java Docs, then don't enforce the rule. A case where it would matter is if anyone ever needs to see that information and doesn't have access to your version control

Answer 3

Well for one thing Javadoc visibility typically transcends source control visibility. I can view the Javadocs for Java 1.1's library but can't to my knowledge freely peruse the Sun's version history from back then.

You're talking as if your Javadocs are completely isolated to you (the developer), and not distributed to others as part of an API, etc. That's not always the case. Usually Javadocs and VCS information serve completely different purposes.

For me, even if I have free access to the version history of a file, I like being able to see it right there in the source, for the same reason that I like comments explaining odd code in the file instead of having to go to the commit description for a certain code block. It's quicker.

Answer 4

I think the @author tag actually confuses things. First of all, if it isn't updated judiciously, it becomes wrong. Also, what if you (not being the original author) change half a class? Do you update the @author? Do you add one? And what if you change only a few lines in the class?

I also think it promotes code-ownership, which I don't think is a good thing. Anybody should be allowed to change a file. If there's an @author tag, people will tend to let this author make all the changes instead of doing it themselves and maybe learning something in the process.

Finally, as you said, the same information, in much more detail, is available from your VCS. Anything you add in Javadoc is duplication. And duplication is bad, right?

EDIT: Other answers mention the fact that you may not have access to the VCS, and in such cases the @author tag is useful. I humbly disagree. In such cases, you're most likely dealing with a 3rd party library, or perhaps an artifact from a different team inside your company. If that's the case, does it really matter who the individual was who created a certain class? Most likely, you only need to know the entity who created the library, and talk to their contact person.

Answer 5

No. The audience of the javadoc pages may not have access to your source control, so this information is relevant.

The @since is important as the documentation may be consulted for older versions of the software. When you can see when a feature was introduced you know 1) that it is unavailable to you and 2) that there is a good reason for upgrading.

You might, however, use an email address for author to contact your team for the @author tag.