Javadoc @author tag good practices

I would say that for most purposes @author is unwanted noise. The user of your API shouldn’t – and probably doesn’t – care, or want to know, who wrote which parts.

And, as you have already stated, SVN already holds this information in a much more authoritative way than the code can. So if I was one of the team, I would always prefer SVN’s log and ignore the @author. I’d bet that the code will get out of sync with reality, whatever policy you adopted. Following the Don’t Repeat Yourself principle, why hold this information in two places?

If, however, there is some bureaucratic or policy reason that this information MUST be included in the code, have you considered automatically updating the @author tag in the code on check in? You could probably achieve this with an SVN hook. You could for example list all the developers who changed a given file in the order they changed it; or who changed it most; or whatever. Or, if the @author is mandated in (source) code you release to the outside world, you could consider adding the @author automatically as part of the release build (I suspect you could get this information out of SVN somehow).

As for adding more than a single class level @author tag (or other comment), I’d say you’d be accumulating a lot of unhelpful noise. (Again, you have SVN.)

In my experience it is much more useful to identify a historical change (say a change to a line of code, or a method), then to work out which change set this relates to (and which track ticket). Then you have the full context for the change: you have the ticket, the change set, you can find other change sets on the same ticket, or around the same time, you can find related tickets, and you can see ALL the changes that formed that unit of work. You are never going to get this from annotation or comments in code.

Leave a Comment