Don’t use the @author Javadoc tag

By Adrian Smith3 Sep 2010300 words2 mins to read

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.

This article was written by Adrian Smith on 3 Sep 2010

Follow me: Facebook | Twitter | Email

More on: Java | Project Management | Coding