The Former Weblog of Peter Ahé

Open sourcing of javac (and the JDK) is an opportunity to revisit our current practices and think about what is missing, what needs to be updated, and what should stay the same. One issue is how to attribute source code with @author tags and there are different policies in use in the open source community.

The position of the Apache Software Foundation (ASF) was explained by the then president of the ASF. To summarize, the ASF recommends against putting @author tags in source code for these reasons:

• Attributions in source files are not up to date.
• Software is a team effort.
• ASF sells the code base as an ASF brand.
• Shield against law-suits.

However, those concerns are not that convincing to me and are far out-weighed by the need for programmers to take responsibility for the code they write. In Pragmatic Programmer: from journeyman to master, Hunt and Thomas recommend that programmers sign their work, tip 70. They further say:

We want to see pride of ownership. I wrote this, and I stand behind my work.

The former president of ASF has a good point that @author tags should be kept up to date. I agree and think the solution is to ensure they are kept up to date with a clear policy and code reviews. For example, if you create a new class or make significant changes to its API add an @author tag. If you make a minor change make sure your name is in the project's contributor file but do not add an @author tag.

Another point made by the ASF is that software is created by a team and the strength of the brand. I agree that software is created as a team and I think that all the team members deserves to be mentioned in a file that lists all contributors. Such a file could be part of the source bundle and also be prominently linked from the website. I don't think the sense of team effort is harmed by adding @author tags to source files and I don't see how it harms the brand, after all, the copyright statements remain and prominently identify the organization.

I am not a lawyer and this is not legal advice: it is plausible that there are people in other countries that should be careful about putting their names in source files because they can be sued. However, I do not see how this affects people that does not live in those countries.

I have long followed the Emacs lisp library header conventions as described in the GNU Emacs Lisp Reference Manual. As a practical matter, I think these can be directly applied to Java source code. When the Emacs lisp convention talks about file header, I think top-level class and package comment. In other words, only package and top-level class comments should contain @author tags.

It is possible to argue that we have a unique opportunity to go and clean up our sources right now before they are released to the public. However, I'm not convinced that this opportunity has not already passed. Some parts of the JDK were open sourced even before javac and HotSpot was opened in November and the public API has been part of the JDK (src.zip) for many releases. Similarly, all the sources of the JDK have been available for download under JRL since late 2004. There are people that are very sensitive to having their @author tags removed, for example, consider how the developer exa felt after he handed over a project and discovered that the new maintainers had removed his name from the source code.

Although we have not consistently used @author tags in the JDK, or even javac, I think we should keep the ones we have already and develop a consistent policy (for example inspired by the Emacs lisp conventions). It may be a good idea to hide email addresses by obfuscating existing @author tags if they contain email addresses.