Janne Jalkanen wrote:
I think we may be reading too much into the ASF guidelines by
recommending we remove @author tags. I know for sure that Apache is
not enforcing this guideline very strictly. For example, look at the
author tags for this source file:
It is a strong SHOULD. And I kinda agree with it.
I agree with Murray: @author tags are valuable because they help
identify expertise and knowledge associated with particular bits of
code. They are good for "archeology." Removing them would do more harm
than good.
I disagree. The SVN log and annotations very clearly spell out who did
what. Are you sure @author-tags are updated every single time? If the
file has patches from several dozens of files over several years, who
really is the author? Is anyone removing @author -tags from code which
no longer has any pieces of the original contribution left?
I don't know anybody who goes to the trouble of reading the SVN logs, and
I think it's not realistic to think anybody who downloads and looks at
code is going to do so. It's not that @author identifies every contributor,
it identifies someone who knows what the code does, why it was written,
and who is most likely to know how to fix or modify it. That is very
valuable information, even for Apache projects.
I'm going to remove all @author tags with my name on them anyway and not
add any new ones. Personally, I would much rather have the team get the
credit than myself. If anyone needs to point any blaming fingers at
anyone, the SVN history tells all that is necessary.
To me, the presence of @author-tags is useless metadata, which causes
more harm than good. Probably because I get all the emails asking for
help, and I need to constantly defer people to the mailing list.
The thing is, while there are certainly patches and changes made over
time to any file, there is *generally* a principal architect and author
of a file who understands/understood how it fit into the greater picture.
And while it's true that not every author remains part of the project,
for those that do it's invaluable to know who did what. Yes, we should
ask the list, but knowing who wrote the majority of the code for say,
the AAA parts of JSPWiki, or a given plugin, is *very* valuable informa-
tion. As someone who's now been working in libraries for awhile, it's a
really, really a bad idea to throw out metadata, even if it's not
*entirely* accurate (and for @author tags, I'd argue that within
limitations, they're largerly accurate for their intended purpose).
Murray
...........................................................................
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
