76

I'm wondering about best practices when creating Javadocs. I have a project with many files. Code has been created by many developers. Each file has an annotation @author, so it is obvious who has created a particular class.

But when some other developer adds new code to a file, modifies it, etc., how should he inform the rest of the team that he has created some new function or has modified existing code? In other words, how should we "keep the Javadocs compatible with reality"? ;)

  • Add his name to the existing @author tag? Then, it is easier to identify who to ask in case of any doubts.
  • Add an @author tag to each new method, inner class, etc.?

Of course, since we use SVN, it is easy to investigate who has made what, but for keeping things clear this Javadoc stuff should be taken into consideration as well.

What's the best way to use these @author tags?

Dan Getz
  • 8,774
  • 6
  • 30
  • 64
radekEm
  • 4,617
  • 6
  • 32
  • 45

9 Answers9

84

I would say that for most purposes @author is unwanted noise. The user of your API shouldn't - and probably doesn't - care, or want to know, who wrote which parts.

And, as you have already stated, SVN already holds this information in a much more authoritative way than the code can. So if I was one of the team, I would always prefer SVN's log and ignore the @author. I'd bet that the code will get out of sync with reality, whatever policy you adopted. Following the Don't Repeat Yourself principle, why hold this information in two places?

If, however, there is some bureaucratic or policy reason that this information MUST be included in the code, have you considered automatically updating the @author tag in the code on check in? You could probably achieve this with an SVN hook. You could for example list all the developers who changed a given file in the order they changed it; or who changed it most; or whatever. Or, if the @author is mandated in (source) code you release to the outside world, you could consider adding the @author automatically as part of the release build (I suspect you could get this information out of SVN somehow).

As for adding more than a single class level @author tag (or other comment), I'd say you'd be accumulating a lot of unhelpful noise. (Again, you have SVN.)

In my experience it is much more useful to identify a historical change (say a change to a line of code, or a method), then to work out which change set this relates to (and which track ticket). Then you have the full context for the change: you have the ticket, the change set, you can find other change sets on the same ticket, or around the same time, you can find related tickets, and you can see ALL the changes that formed that unit of work. You are never going to get this from annotation or comments in code.

Paul
  • 3,009
  • 16
  • 33
  • what annotation should be given for programmer who updated the code? – tvshajeer Feb 28 '15 at 10:22
  • 4
    @tvshajeer: no annotattions, just use git or svn to check who changed what. Author annotation also mitigates the idea of collective code ownership – Mari Aug 04 '15 at 14:41
  • 3
    Unwanted **by whom?** What possible value is there in suppressing that information? – user207421 Nov 17 '16 at 09:18
  • I strongly disagree. The point of javadoc has always been immediate information: You *could* look up method signatures by examining the code, but reading javadoc is *much faster* (nearly instantaneous, in fact). Same goes for @author tags compared to version control. If you really don’t want the target audience to see the authors, just don’t use the `-author` option when generating the docs. – VGR Nov 17 '16 at 13:11
  • 7
    @VGR One of the code bases I work on has ~1,000,000 lines of Java developed over ten years with ~8,000 classes. The majority *do* have author tags. Of these: they usually only name the person who created the class; 4 of the 5 people named no longer work for the company; very many have since been modified so much that they would be unrecognizable by the named developer anyway; many are wrong as they were copied when the class was derived from a similar class. In reviewing either source or generated docs they're noise wasting screen space and hence impeding comprehension. – Paul Jan 19 '17 at 21:39
  • 1
    @VGR That said, I have no issue with author tags in, say, an open source project were they serve to attribute credit. Or in a library were different sub-packages really are developed largely be different people (hence they really *do* tell you something useful). But my experience suggests that in most real projects, most of the time, they really are just noise (or vanity). – Paul Jan 19 '17 at 21:45
  • @EJP What's suppressed? Any professional dev. team will be using a version control system. Very many open source projects have their version control system publicly visible anyway. That system will be able to tell you: what changed (down to individual parts of lines); when (to the second); who changed it; and what release it was in. If linked to the ticket system probably also: why; who reviewed it; what improvements or refactorings were made; what unit tests were created; who tested it. Why keep a second inferior, incomplete, probably inaccurate additional 'copy' of this information? – Paul Jan 19 '17 at 22:01
  • 3
    Lot's of projects have change source code system where all that author history has been lost – jasonoriordan Feb 28 '17 at 10:40
  • @jasonoriordan How would they lose the author history? Any project that has allowed that to happen sounds like an epic fail to me. Or are you saying they never used a version control system in the first place? I've never encountered any such case. – Paul Apr 05 '17 at 16:28
  • 1
    @Paul, sometimes SCMs are managed externally from your team (specially on large corporations). Any given day, *they* might suddenly decide to migrate all source code from VendorA to VendorB, losing all history (for whatever reasons that are beyond your paygrade). I've seen this a couple of times and then you start suffering because you have lost all track forever. – DanielCuadra Dec 12 '17 at 18:20
  • 1
    @DanielCuadra If that was a real possibility, I'd run in internal VCS and push from that to the company-wide one. Any company, organisation, dept deliberately binning all their version history (for reasons above the team's pay grade, or not) has already failed due diligence in software development. – Paul Jul 12 '18 at 14:18
27

You may want to consider why you want author tags in the source. The Apache Foundation do not and I agree.

https://web.archive.org/web/20150226035235/www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

To my best understanding this is a cargo cult way of working from when sources were printed on paper. With modern version control systems this information and more can be found in the history anyway.

Captain Man
  • 6,997
  • 6
  • 48
  • 74
Thorbjørn Ravn Andersen
  • 73,784
  • 33
  • 194
  • 347
13

You can have more than one @author tag. In case you make some big changes to a class, just add a new @author tag with your own name in it. There's no need to mark the changes you've done or to put your name around the changes, as the revision history should be able to display that clearly.

Juned Ahsan
  • 67,789
  • 12
  • 98
  • 136
10

In really big and long-running projects with lots of developers, it is useful to know ho is responsible for given code, who can provide you with extra information and such. In that case it would be handy to have such an informationin the file using @author tag. Not marking who created the file or who made some major contributions, but who is a contact person for that code. Those might be very different people as original author may be already on different project or left the company years ago.

I think on huge project that approach may be handy, however there is a caveat. Keeping every single file's author information is very difficult as there is huge amount of files and sooner or later will fail. More and more files will have outdated information and developers will no longer trust this @author as source of information and will just ignore it.

Solution, which may work, is not to keep @author on every single file, but only per module (high level packages). Javadoc has a feature, where you can document not only files but whole packages (See this question for more detail).

This is however a special case and as long as your project is not that big or old, I reccomend ommiting the author information.

Community
  • 1
  • 1
Vojtech Ruzicka
  • 16,384
  • 15
  • 63
  • 66
8

I completely agree that it is unnecessary and you probably shouldn't add it. However I still add it, I see it like adding a signature to a painting, or adding it to a stamp on a piece of metal in a computer helped design. You wrote that piece of code, and adding your name shows that you are proud of it and that you are confident of its quality, even if it does nothing else. Even if it's changed in the future, you laid the foundations for everything built on top of it, and should it really be rewritten completely, the tag can be changed, removed or expanded. I agree that it is redundant thanks to version control, but having your name in version control isn't nearly as satisfying. If someone just adds a "final" or formats the code, their name will be in version control, even if they hardly contributed at all. I also agree that it is noise, in that it doesn't add anything to the code, however is it really even slightly noticeably annoying? I don't think so. If you are reasonable about it, I think it can make a project "more friendly", if that makes sense.

Andreas Hartmann
  • 1,825
  • 4
  • 23
  • 36
  • Hi, thanks for answering this question :) I can tell you, that from some perspective I am not a fan of using this tag any more. Code it a team work, and as long as such tag can be - as you mentioned - treated as a kind of a painter's signature,I think the code is not a place for such actions ;) Of course there could be some situation where such approach is reasonable (for exanoke adding the entire team as an author so other teams know who is responsible for some feature) but as a rule of thumb I'd not use it quite often. "If you are reasonable about it" - agreed - that is a key point here;) – radekEm Jan 16 '19 at 09:40
  • Yes, it very much depends on the context/team you are working in. By default it shouldn't be used, but in some environments it might slightly increase quality or satisfaction. – Andreas Hartmann Jan 16 '19 at 13:13
5

It is the year 2021, and when I am replying to this question, it is nearly 8 years from the first publish. The world is a little bit different place and it is using microservices at full throttle. Therefore, I would sum up the overall mood around authorship like this: it is pointless. Let me explain it on a few points:

  • Most widespread software or organisation projects are developed by multiple authors, not individuals anymore.
  • Majority of software is versioned in Git, CI/CD and cloud is reachable reality.
  • Advanced IDEs visualise greatly code changes. Code changes are more important than the overall class source code.
  • Handling bugs caused by code changes are far more important than handling bugs caused by the usage of the wrong class version.
  • Unless the software is a library, IP/commercial software, framework with regular releases, authorship has no meaning.
  • It is highly probable that the authors of the source code you use/work on are not working or never work in your organisation.
  • Maintaining an appropriate ratio of author contribution in author declaration leads to additional effort with 0 gain. Nobody wants that.

Therefore, knowledge of simple code edits and appropriate line changes are more important than knowledge of the whole class.

Here is my opinion on class authorship digested to the short article.

Pang
  • 9,564
  • 146
  • 81
  • 122
Andrej Buday
  • 559
  • 5
  • 14
3

It's very handy to have @author tag and have multiple authors. Even Oracle's Documentation outlines that it's good practice to have @author on top of class to give credit to particular author who did the job and also to track down things if someone needs to be spoken to during development process. If there are multiple authors they can be listed in order they contributed on a particular java file/class. Yes, there are plugins and with git structure, you can check can see author's name hanging around in the code precisely, but this idea will be controversial though. Because, sometimes multiple authors edit same line of code and might not show two authors editing same line of code. I have plugin enabled, it never shows 2 authors name for editing same line of code. With big companies, it's handy to have this practice set up.

surendrapanday
  • 530
  • 3
  • 13
2

If it is company code, I would not do that: we have VCS. Instead, if it is a blog post or code snippets of my personal repo, I would proudly add this and hoping some copy-paste guy will find my code useful and accidentally, copy my name as well :)

Just my type of humour, I guess.

WesternGun
  • 11,303
  • 6
  • 88
  • 157
0

Building off of this answer and digging through links from posts from 2004 I found this (pasted below). It's from Dirk-Willem van Gulik who was one of the founders of the Apache Software Foundation so I assume he had some input on the decision to stop using @author tags.

List:       xml-cocoon-dev Subject:    Re: @author tags (WAS: RE: ASF
Board Summary for February 18, 2004) From:       Dirk-Willem van Gulik
<dirkx () asemantics ! com> Date:       2004-02-27 10:33:32
Message-ID: 63E38432-6910-11D8-BA7E-000A95CDA38A () asemantics ! com

On Feb 27, 2004, at 12:45 AM, Conal Tuohy wrote:

I don't think the ASF should discourage developers from keeping useful metadata about the code inside the source files. What better place to put the metadata than in the code? This makes it more likely to be used and kept up to date than if it was stored somewhere else, IMHO.

One way to look at this is that @author tags are in a way factually 'wrong'; in most cases it just signals which person wrote the first skeleton of that code; but subsequently it was fixes, peer-reviewed and looked at by a whole community. Also do not forget the many people in your community which help with QA, Documentation, user-feedback and so on. To put one person in the (hot) seat for what is essentially a group effort is not quite right.

Looking through the CVS logs of a few tomcat files: each block of 30 lines seems to have had commits of at least 5 persons; with a median of 6 and an average of 9. The average number of @author tags on those arbitrary blocks is about 0.5. And that is not counting QA, docs, suggestions of mailing lists, bug resolutions, user support. I.e. those things which make tomcat such a great supported product.

Secondly what we 'sell' as the ASF brand is a code base which is peer reviewed, quality controlled and created by a sustainable group which will survive the coming and going of volunteers. One where knowledge is generally shared and not just depended on one single individual. This is one of the key reasons why large companies, governments, etc have a lot less qualms about using apache than using most other open source; we mitigate the worry that it depends on a single person, and can implode or fork without warning, right from the get-go.

Finally - a lot of developers do live in countries where you can get sued. The ASF can provide a certain level of protection; but this is based on the KEY premisse that there is oversight and peer review. That what we ship is a community product; and that everything is backed by the community and cannot be attributed to a single person. Every commit gets peer review; ever release requires +1s' and are backed by the community as a whole. @author tags are by necessity incomplete and thus portrait the situation inaccurately. Any hint or suggestion that parts of the code are not a community product makes defence more complex and expensive. We do not want to temp anyone - but rather present a clean picture with no blemishes or easy go's.

And to give this a positive slant; be -proud- of this culture; be proud of being part of something larger of incredible quality. Each of you did not just write a few pesky lines of code surrounded by an @author tag; but where instrumental in getting the -whole- thing work ! And if you are ever trying to understand why cocoon made it this far, and other commercial/open-source projects did not, then do look there; quality and a sense of long term stability.

Take Care, Have fun,

Dw

While tracking this down I came across a few blog posts against this and some in favor. That's a very small sample size but I think it is fair to say this was at least a controversial change -- some folks wanted them to stay. That said, in 2022 I don't really ever see them used. (Remember, this mail is from 2004.) You even mentioned it yourself about SVN history (but now maybe Git is the more common tool) and even in this mail they mention the CVS logs (another source control tool). Maybe the source control tools of today are easier to use, who knows.

I feel like there still might be some oddball use cases that make sense but I don't think the standard idea of "I wrote (or modified) this so I'm putting myself as the @author" is necessary. I currently have a question on Code Review about using it for Creative Commons attribution and (in my opinion) I think it's a good use but I would hardly call that a well-accepted good practice (but I don't think it hurts).

Captain Man
  • 6,997
  • 6
  • 48
  • 74