Uploaded image for project: 'Apache Taverna'
  1. Apache Taverna
  2. TAVERNA-897

Remove @author tags?

    XMLWordPrintableJSON

Details

    • Bug
    • Status: To Do
    • Major
    • Resolution: Unresolved
    • None
    • None
    • None
    • None

    Description

      Some of our Javadoc contain @author tags - which are reflected in the HTML of the JAvadoc - for instance

      http://taverna.incubator.apache.org/javadoc/taverna-language/org/apache/taverna/scufl2/api/package-summary.html

      http://taverna.incubator.apache.org/javadoc/taverna-osgi/org/apache/taverna/configuration/ConfigurationManager.html

      Apache NiFi's argument against Javadoc @author tags: http://mail-archives.apache.org/mod_mbox/incubator-nifi-dev/201505.mbox/%3CCAGHyZ6LcrZ1aPMUjJ%3DrJkkK19Cmveew7PmTUKuWprK_bz3jxmg%40mail.gmail.com%3E – which I find myself agreeing with.

      Older discussion also says Apache projects should stay away from @author tags:
      https://mail-archives.apache.org/mod_mbox/www-community/200306.mbox/%3C20030609234538.GA22335@lyra.org%3E

      A simple argument is that under ASF all of the Taverna committers are equally responsible or attributable for all the code base - even if a particular person made a class to start with.

      Maintenance of @author tag is error-prone (how big a change before you add yourself? What about thousands of files with no @author?)

      Also there's the question of what is the purpose of the @author tag beyond attribution (it shows up in the HTML representation), when any questions about a class should be taken to dev@taverna - not to that person.

      The git log should provide attribution about who made a file, but sadly after various folder/repository moves and version control system changes this is a bit tricky (you need to use git log --follow and hope for the best). So there is an counter-argument for keeping the @author tags - specially as coming up in TAVERNA-894 lots of the classes of taverna-osgi and taverna-engine were initially written by David Withers and Tom Oinn, and neither joined the Apache Taverna project.

      What are your views?

      Attachments

        Issue Links

          Activity

            People

              stain Stian Soiland-Reyes
              stain Stian Soiland-Reyes
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

                Created:
                Updated: