Don’t use the @author Javadoc tag

In Javadoc there is an @author tag so you can specify who originally wrote the class, method, etc., being documented.

/**
 * This represents a user of the system as stored in Oracle.
 * @author Adrian Smith
 */
class User { ... }

But really, what's the point, when version-control tools such as "svn log", "svn blame" and exist? (And any project where it would be necessary to determine the author necessarily involves more than one person, any (at least) any project involving more than one person requires a version control system.)

I suppose there could be a case for using @author in the cases that the source is distributed without any version control information. But at least on the projects I work on, that's never the case.

The project I'm currently working on has random @author tags all over the place, due to various copy/paste action and refactoring. The @author tag bears no relation to the person who last changed the code, who knows about it, or even who's still in the company. Wrong documentation is worse than no documentation, as you might be tempted to believe wrong documentation.

P.S. I recently created a nerdy privacy-respecting tool called When Will I Run Out Of Money? It's available for free if you want to check it out.

This article is © Adrian Smith.
It was originally published on 3 Sep 2010
More on: Java | Project Management | Coding