[Discussion] How should we be using @author JavaDocs tags?

[Tim Donohue]

Hi Developers,

I'm writing to ask your individual opinions on a "hot topic" discussion that has come up in today's DevMtg [1] and within PR #1884 [2]. 

Do we, as DSpace Developers, wish to establish any policies or best practices around usage of JavaDocs "@author" tags [3] in our code? 

Currently, these @author tags are considered optional, and are not formally utilized in any way (e.g. DSpace contributors lists are generated using GitHub commits and not these tags).

The following questions have originated out of this discussion, and I'd appreciate your individual feedback on any (or all) of them. Below these questions, I've also included some data points from *other* open source projects (which you may wish to read before answering).

1) Should "@author" tags be required? optional? banned? in DSpace code

2) If allowable, what do you feel is the purpose of "@author" tags?  Should they refer to major contributors to the code (i.e. give credit to significant work)?  Should they provide information about who to contact regarding this code?  Or, perhaps, both?

3) Finally, if allowable (and based on #2), what sort of information would you like to see in "@author" tags?  Individual names?  Affiliations?  Email addresses?  GitHub IDs?  Organizational names only (with possibly no individuals mentioned)?  Some combination of these?  Are there any of the above you feel should *not* be allowable in an "@author" tag?

I'd appreciate your personal opinion on the above questions, as it may help inform our final decision and (draft) Code Style Guide for DSpace [4].

================================================

What do other projects do? Additional data points to consider

================================================

Apache Foundation:  The Apache Foundation has banned all usage of "@author" tags in its project codebases. This policy seems to be based on their belief that the tags are often outdated & not very useful. Instead, they seem to rely on code history (in Git, SVN, etc) to diffinitively determine who contributed to specific code (and/or who to contact about that code). Reference: http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

Fedora Repository (another DuraSpace project): The Fedora project requires "@author" tags at the class level (this is enforced by CheckStyle rules). In discussion with Andrew Woods (Fedora Tech Lead), he noted they treat these tags as "hint[s] as to who to ask questions of related to the code". The tags are used to refer to individuals by name or some personal "handle" (e.g. GitHub username). By practice, they do not tend to include emails or affiliations / organizational names (as those may change when individuals get a new job, etc).

[1] http://irclogs.duraspace.org/index.php?date=2017-11-29 

[2] https://github.com/DSpace/DSpace/pull/1884#pullrequestreview-79593864 

[3] Javadocs "@author" tag: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@author 

[4] (Draft, in progress) DSpace Code Style guide: https://wiki.duraspace.org/pages/viewpage.action?pageId=90967266 

- Tim

--

Tim Donohue
Technical Lead for DSpace & DSpaceDirect
DuraSpace.org | DSpace.org | DSpaceDirect.org

[Mark H. Wood]

I will start by noting that the standard doclet has to be told to
process @author. By default, apidocs output does not include it. I
feel that this reduces the value of the tag somewhat. Because of
this, I don't have a strong feeling about whether we should or should
not have these tags. I do feel that it's reasonable to have a
standard.

I feel somewhat more strongly about the content of the tags.

I always thought that the purpose of this tag was to identify the
original creator(s) of the code in a class, to help in getting answers
about the overall design of the class.

An analogy may be in order: authors of books may include informal
front-matter notes or formal Acknowledgements of people who
contributed to the author's thinking, but those people are not
credited as co-authors if they didn't do any of the writing, no matter
how formative of the work their association with the author may have
been.

Aside: my own practice has generally been to give credit for significant
non-code contributions by noting the contributor in the ordinary text
of doc comments, as close to the affected code as possible, and to
cite uses of freely copyable code in plain commentary where they
occur.

Another factor which reduces the value of this tag is that any
information other than an individual's name may easily become stale.
(Some cultures change names, too, for example at marriage.)
People change employers, email and physical addresses from time to
time. Maybe an ORCiD or something like it would be the most durable
link to an individual.

Given the weaknesses inherent in the tag, it may be best not to use
it. (Now I need to find out how to adjust NetBeans to not
automagically insert it in my own creations.)

I question the value of an author record that doesn't name a specific
author. Business entities don't write software and can't explain it;
individuals do and can. You can include any number of @author tags, I
think.

--
Mark H. Wood
Lead Technology Analyst

University Library
Indiana University - Purdue University Indianapolis
755 W. Michigan Street
Indianapolis, IN 46202
317-274-0749
www.ulib.iupui.edu