Javadoc @author tag good practices

Question

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 @au

Answer 1

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.