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.)
- The information in version-control log is always accurate
- The information in the source file might originally have been accurate, but the class may have been heavily refactored by someone else
- Some people start classes by copy/pasting another file and changing it: the tag will be wrong in those cases (the people who do that aren't going to be the people who read/write/update doc)
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.