Source Code Headers

[cziegeler]

Hi,

I noticed that we don't consistently use javadoc tags throughout our
code base. Some of them have author tags, others have version tags, some
have both, and a lot of them don't have any tags at all.

For the author tag: it's a suggestion from the ASF to not use author
tags for several reasons (they get out of date/sync, they might be
abused, they imply code ownership etc.). We've seen all this happen at
the ASF, so I suggest to simply remove them. If noone objects, I'll do
that. (the svn history contains exact information about who changed what)

I have no real opinion about the version tags, but as Ate told me these
are used by Jetspeed as well, so I think it makes sense to add them to
all Java source code. Again, if noone objects I'll add them as well.

WDYT?
Carsten
--
Carsten Ziegeler
cziegeler@...

[David Sean Taylor]

On Apr 8, 2009, at 5:36 AM, Carsten Ziegeler wrote:

> Hi,
>
> I noticed that we don't consistently use javadoc tags throughout our
> code base. Some of them have author tags, others have version tags,  
> some
> have both, and a lot of them don't have any tags at all.
>
> For the author tag: it's a suggestion from the ASF to not use author
> tags for several reasons (they get out of date/sync, they might be
> abused, they imply code ownership etc.). We've seen all this happen at
> the ASF, so I suggest to simply remove them. If noone objects, I'll do
> that. (the svn history contains exact information about who changed  
> what)
>

Where does the ASF suggest removing author tags? Is it on the website  
under a policy page, could you please send us a link?
Im  not convinced we should be changing this policy at Pluto right  
now. Yes, the tags can be abused, but I don't follow the logic in  
simply abolishing things that can be abused.
AFAIK, its a per project decision. If all other projects at Apache are  
doing away with author tags, then we should follow policy. I just  
haven't seen other projects Im working with doing so.

[djencks]

On Apr 8, 2009, at 10:55 AM, David Sean Taylor wrote:

>
> On Apr 8, 2009, at 5:36 AM, Carsten Ziegeler wrote:
>
>> Hi,
>>
>> I noticed that we don't consistently use javadoc tags throughout our
>> code base. Some of them have author tags, others have version tags,  
>> some
>> have both, and a lot of them don't have any tags at all.
>>
>> For the author tag: it's a suggestion from the ASF to not use author
>> tags for several reasons (they get out of date/sync, they might be
>> abused, they imply code ownership etc.). We've seen all this happen  
>> at
>> the ASF, so I suggest to simply remove them. If noone objects, I'll  
>> do
>> that. (the svn history contains exact information about who changed  
>> what)
>>
>
> Where does the ASF suggest removing author tags? Is it on the  
> website under a policy page, could you please send us a link?
> Im  not convinced we should be changing this policy at Pluto right  
> now. Yes, the tags can be abused, but I don't follow the logic in  
> simply abolishing things that can be abused.
> AFAIK, its a per project decision. If all other projects at Apache  
> are doing away with author tags, then we should follow policy. I  
> just haven't seen other projects Im working with doing so.

  I googled a bit.  Around 2004 I found a bunch of emails explaining  
that projects were removing author tags as a result of a board  
recommendation to do so.  I have a faint recollection that this might  
have been associated with the apache license change.  I haven't been  
able to locate the recomendation.  It does appear to be a project's  
decision.

I don't think its important one way or the other but I personally  
prefer no author tags.  I've never seen them be maintained.

thanks
david jencks

>
>
>

[Ralph Goers]

On Apr 8, 2009, at 11:47 AM, David Jencks wrote:

>>
>
> I googled a bit.  Around 2004 I found a bunch of emails explaining  
> that projects were removing author tags as a result of a board  
> recommendation to do so.  I have a faint recollection that this  
> might have been associated with the apache license change.  I  
> haven't been able to locate the recomendation.  It does appear to be  
> a project's decision.
>
> I don't think its important one way or the other but I personally  
> prefer no author tags.  I've never seen them be maintained.
>>

I actually like what some of the commons projects have started to do.  
They use the @author tag but the author is a link to the team list  
generated by the list in the maven pom.xml.

Ralph

[Ate Douma]

Carsten Ziegeler wrote:

> Hi,
>
> I noticed that we don't consistently use javadoc tags throughout our
> code base. Some of them have author tags, others have version tags, some
> have both, and a lot of them don't have any tags at all.
>
> For the author tag: it's a suggestion from the ASF to not use author
> tags for several reasons (they get out of date/sync, they might be
> abused, they imply code ownership etc.). We've seen all this happen at
> the ASF, so I suggest to simply remove them. If noone objects, I'll do
> that. (the svn history contains exact information about who changed what)

Personally, I'm not really "attached" to the author tags, but I also agree with David Taylor that removing them just because they *could* be
abused doesn't sound like a good enough reason to me.
We (the PMC) are here to monitor and watch against things like that.
Furthermore, I don't recall this to be a formal ASF policy either, so its up to each project to decide upon.
With that in mind, I think I prefer keeping the author tags for now, until we (the PMC) formally decide otherwise.

>
> I have no real opinion about the version tags, but as Ate told me these
> are used by Jetspeed as well, so I think it makes sense to add them to
> all Java source code. Again, if noone objects I'll add them as well.
Yes, we do use them in Jetspeed and I think the @version $Id$ tag really is a good help to determine what the exact origin is of a source
file at any time.
However, to make use of the subversion $Id$ keywords property requires each (text) source file has this property set.
This depends on the developer to have its local subversion configuration setup correctly which isn't always done right :)
So, to apply the version tag to all source files does require quit some effort.
I've used a custom shell script in the past against Jetspeed (setting the needed svn properties) which helps a lot, but adding the @version
tag is more difficult to automate. And there are still many source files in Jetspeed for which this hasn't been done.
If you are willing to do all that work for Pluto, you've got my +1 :)
But I don't consider this a *required* fix for the upcoming Pluto 2.0 release.

Regards,

Ate

>
> WDYT?
> Carsten

[cziegeler]

Ate Douma wrote:

> Carsten Ziegeler wrote:
>> Hi,
>>
>> I noticed that we don't consistently use javadoc tags throughout our
>> code base. Some of them have author tags, others have version tags, some
>> have both, and a lot of them don't have any tags at all.
>>
>> For the author tag: it's a suggestion from the ASF to not use author
>> tags for several reasons (they get out of date/sync, they might be
>> abused, they imply code ownership etc.). We've seen all this happen at
>> the ASF, so I suggest to simply remove them. If noone objects, I'll do
>> that. (the svn history contains exact information about who changed what)
>
> Personally, I'm not really "attached" to the author tags, but I also
> agree with David Taylor that removing them just because they *could* be
> abused doesn't sound like a good enough reason to me.
> We (the PMC) are here to monitor and watch against things like that.
> Furthermore, I don't recall this to be a formal ASF policy either, so
> its up to each project to decide upon.
> With that in mind, I think I prefer keeping the author tags for now,
> until we (the PMC) formally decide otherwise.

Ok, as I said it is not an official policy it's a suggestion which is
some years old; I didn't find any pointers.
Now, just look at some of our author tags and you can already see that
some of them are plainly out dated or wrong.
And finally, we had this discussion two years ago and before (I couldn't
find all the pointers as searching through the mailing list archives is
a pain). The last time was in march 2007 with the result that I removed
author tags from Pluto - and now we have them back in in some source files.
If author tags are maintained properly and applied to all source files
I'm fine with leaving them in; but as this is not the case and as we
agreed a long time ago for Pluto to remove them, I really think we
should remove them.

Carsten
--
Carsten Ziegeler
cziegeler@...

[cziegeler]

I guess as we can't agree on these things before the Pluto release, I
suggest we leave it as it is for now.

Carsten
--
Carsten Ziegeler
cziegeler@...