Consider removing @author javadoc, document policy

I saw a number of projects making the choice to remove @author tags from their JavaDocs (https://github.com/checkstyle/checkstyle/issues/5738 for example).

I thought it was a good choice - this is a collaborative project that has been going for years with over a hundred contributors and very few classes have only one contributor.

I removed all the @author javadoc tags thinking this was not a controversial choice. I didn’t even send it through PR. That was wrong to do.

@PauloMigAlmeida asked that we bring them back and I realized that I had not given the change sufficient consideration. I reverted the change in https://github.com/github-api/github-api/commit/a42305dd59f0be426f0c9091748e947f60d76bcd so that we can discuss and do this right.

Paulo, could you talk about reasons to keep them? Perhaps we can address your concerns with something other that this particular JavaDoc tag?

[PauloMigAlmeida]

@bitwiseman first of all, it was really nice of you to revert the commit. I commend you for doing that.

My 2 cents on whether keep or not the @author on the source code is … We should keep them because:

1. From the performance/software quality point of view, it doesn’t impact the way it works.
2. Keeping them can be interpreted (by some people) as a way of the open-source community express their gratitude for the time and effort that the author put into crafting that piece of code.
3. This is a common practice on lots of projects too: For instance, OpenJDK, Spring boot, Linux Kernel
4. This is a personal one but I confess that I got to know several incredibly brilliant people by reading the @author. For instance:
   1. by reading some of the java classes I learnt about Joshua Bloch, which eventually led me to his legendary book ‘Effective Java’.
   2. by doing a similar thing, I learnt about Ingo Molnar and his astonishing work on the CFS.
   3. The same goes to this library, I was looking into some of Kohsuke’s work while he was working at Sun that eventually led me to this project. And this led me to become a contributor and also to learn about @bitwiseman and his great work in a project that wasn’t being proactively looked after.

I’m aware of things like:

• If you want to know who committed a piece of code, just traverse through the git tree and you will find out who committed.
• It’s hard to keep them up-to-date.
• We could use the <contributor> XML elements on the pom.xml for that purpose.

My thoughts on them are that either they don’t cover all edge cases or they make the discovery part (knowing who did what/when) a bit harder. That’s why we should have multiple discoverable ways available to make things easier rather than harder and since this isn’t impacting the library performance-wise then let’s keep it 😃

So all in all, this should be a matter of choice… if the person who committed a piece of code feels comfortable not adding a @author tag then he/she can do so. The same should work the other way around.

[PauloMigAlmeida]

Super! Thanks for being so flexible. 😃

Regarding the documentation task, leave that one to me. I will open a PR soon 😃