Consider removing @author javadoc, document policy

[bitwiseman]

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.

[bitwiseman]

@PauloMigAlmeida No problem. Thanks for speaking up.

I'm going to leave this open for a bit in case anyone wants to make a case in favor of removal. If not, I'll be happy to close this as "By design".

In that case, I'll need to figure out some place to track "project code style and policy" decisions like this one. (An example of a similar decision would be the choice to enforce automated code formatting.)

[chids]

Adding my two cents, fwiw.

I've personally never seen much value in @author in Javadocs. The actual author data is available source control (both through history and, on Github, through the contributor page of the repo).

@PauloMigAlmeida makes a good and, to me, valuable point in recognising contributors. For this I feel that showing gratitude and giving recognition through a dedicated contributor page/list, like so, actually puts it more front and center than having @author tags.

While I wouldn't add @author for stuff I contribute nor would I advocate their use in any project I don't care if they're there or not.

[PauloMigAlmeida]

@bitwiseman Have you come to a conclusion regarding this issue?

[bitwiseman]

@PauloMigAlmeida

Yes, I'm going to leave them in. 🤷 I respect your strong view of them and they are only minimal added text.

I may even tag some classes with my own name. 😄

This is now a documentation task. We need to create a document such as DEVELOPER.md (or add to CONTRIBUTING.md) to describe code style decisions such as this one.

[PauloMigAlmeida]

Super! Thanks for being so flexible. 😃

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