I'm wondering about best practices when creating Javadocs. I have a project with many files. Code has been created by many developers. Each file has an annotation @author, so it is obvious who has created a particular class.
But when some other developer adds new code to a file, modifies it, etc., how should he inform the rest of the team that he has created some new function or has modified existing code? In other words, how should we "keep the Javadocs compatible with reality"? ;)
- Add his name to the existing
@authortag? Then, it is easier to identify who to ask in case of any doubts. - Add an
@authortag to each new method, inner class, etc.?
Of course, since we use SVN, it is easy to investigate who has made what, but for keeping things clear this Javadoc stuff should be taken into consideration as well.
What's the best way to use these @author tags?
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.
You may want to consider why you want author tags in the source. The Apache Foundation do not and I agree.
http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags
To my best understanding this is a cargo cult way of working from when sources were printed on paper. With modern version control systems this information and more can be found in the history anyway.
You can have more than one @author tag. In case you make some big changes to a class, just add a new @author tag with your own name in it. There's no need to mark the changes you've done or to put your name around the changes, as the revision history should be able to display that clearly.
In really big and long-running projects with lots of developers, it is useful to know ho is responsible for given code, who can provide you with extra information and such. In that case it would be handy to have such an informationin the file using @author tag. Not marking who created the file or who made some major contributions, but who is a contact person for that code. Those might be very different people as original author may be already on different project or left the company years ago.
I think on huge project that approach may be handy, however there is a caveat. Keeping every single file's author information is very difficult as there is huge amount of files and sooner or later will fail. More and more files will have outdated information and developers will no longer trust this @author as source of information and will just ignore it.
Solution, which may work, is not to keep @author on every single file, but only per module (high level packages). Javadoc has a feature, where you can document not only files but whole packages (See this question for more detail).
This is however a special case and as long as your project is not that big or old, I reccomend ommiting the author information.
I completely agree that it is unnecessary and you probably shouldn't add it. However I still add it, I see it like adding a signature to a painting, or adding it to a stamp on a piece of metal in a computer helped design. You wrote that piece of code, and adding your name shows that you are proud of it and that you are confident of its quality, even if it does nothing else. Even if it's changed in the future, you laid the foundations for everything built on top of it, and should it really be rewritten completely, the tag can be changed, removed or expanded. I agree that it is redundant thanks to version control, but having your name in version control isn't nearly as satisfying. If someone just adds a "final" or formats the code, their name will be in version control, even if they hardly contributed at all. I also agree that it is noise, in that it doesn't add anything to the code, however is it really even slightly noticeably annoying? I don't think so. If you are reasonable about it, I think it can make a project "more friendly", if that makes sense.
It's very handy to have @author tag and have multiple authors. Even Oracle's Documentation outlines that it's good practice to have @author on top of class to give credit to particular author who did the job and also to track down things if someone needs to be spoken to during development process. If there are multiple authors they can be listed in order they contributed on a particular java file/class. Yes, there are plugins and with git structure, you can check can see author's name hanging around in the code precisely, but this idea will be controversial though. Because, sometimes multiple authors edit same line of code and might not show two authors editing same line of code. I have plugin enabled, it never shows 2 authors name for editing same line of code. With big companies, it's handy to have this practice set up.
If it is company code, I would not do that: we have VCS. Instead, if it is a blog post or code snippets of my personal repo, I would proudly add this and hoping some copy-paste guy will find my code useful and accidentally, copy my name as well :)
Just my type of humour, I guess.
来源：https://stackoverflow.com/questions/17269843/javadoc-author-tag-good-practices