Janne Jalkanen wrote:
> I am totally uncertain as to what the @authorship really signifies or > what the benefit of it is. [...]
So what is the *real* use of knowing the original author of the code which has been rewritten a dozen times over - or someone who has not contributed in five years and nobody knows how to contact anymore?
This I believe has been answered several times. As Andrew just replied, > An "author," it seems to me, is the person (or person) who did the > preponderance of the work initially, or as part of an enhancement. By > "the work," I mean the conception, design, coding, test-case writing and > debugging. That rules out bug-fixing, unless the bug was so gnarly that > it necessitated a gut-rewrite or major refactoring. It also rules out > Javadoc tweaks. [...] > Thus: if you design, write/enhance code, and write unit tests, you might > be an author. If you fix a bug, you probably aren't. And as I wrote: > the original author of a class is the one identified in the @author tag, > with the understanding of what that means, i.e., that that does not (nor > would anyone believe) include everyone who has touched that file. It does > (as I wrote) state who initially wrote it, who knew the reason for it, and > who is most likely (if they are still around) to understand it. [...] If > I note that the person identified in the @author tag hasn't been seen for > two years, then I would expect that I'd be mostly on my own. It is in > either case valuable information. We *all* understand that for any given file it may have been touched and modified by many people over time. The @author tag does not identify them, it merely identifies the originating author, or someone who has made a very significant alteration to the code, not bug fixes or changes to the documentation. As you wrote, the SVN logs provide that information. And whatever might be deemed authoritive, from the Java site: "You can provide one @author tag, multiple @author tags, or no @author tags. In these days of the community process when development of new APIs is an open, joint effort, the JSR can be consider the author for new packages at the package level. For example, the new package java.nio has "@author JSR-51 Expert Group" at the package level. Then individual programmers can be assigned to @author at the class level. As this tag can only be applied at the overview, package and class level, the tag applies only to those who make significant contributions to the design or implementation, and so would not ordinarily include technical writers." "The @author tag is not critical, because it is not included when generating the API specification, and so it is seen only by those viewing the source code. (Version history can also be used for determining contributors for internal purposes.)" [1] So it would seem that at the class level, an @author tag is considered appropriate, even with community projects, with the version history providing the who's-who on bug fixes and individual, minor changes. As according to Sun. ---- I think it would have been more fair to simply state that you disagree with their use; there has been *plenty* of explanation on the list of how some of us use and value the information in @author tags, and how they can be used effectively (knowing their limitations), even in the case when authors/contributors are no longer around (again, that is also valuable information). And if I'm being fair I'll also add that (as an author) I *do* find it quite offensive when people remove my name from things I've written and bothered to sign, particularly against my wishes -- and believe me, I'm hardly in this for the "fame". But if someone is encouraged to contribute to a project because they do have the possibility of putting their name on something, that's great, we can always use more contributors. [And this is of course not a call to have people abuse @author tags -- there is an acceptable use most everyone would agree upon, as described previously and above.] Murray [1] http://java.sun.com/j2se/javadoc/writingdoccomments/[EMAIL PROTECTED] ........................................................................... Murray Altheim <murray07 at altheim.com> === = = http://www.altheim.com/murray/ = = === SGML Grease Monkey, Banjo Player, Wantanabe Zen Monk = = = = Boundless wind and moon - the eye within eyes, Inexhaustible heaven and earth - the light beyond light, The willow dark, the flower bright - ten thousand houses, Knock at any door - there's one who will respond. -- The Blue Cliff Record
