dhis2-devs team mailing list archive

[Bob Jolliffe <bobjolliffe@xxxxxxxxx>]

Hi Hieu

After thinking about your problem some more I think we do have a style issue
to sort out.  Whereas @author and @version tags have some generally
understood meaning the reality is that the actual meaning of them (and
others like @since) is an in-house style decision.

There's an interesting general discussion of javadoc tags here:
http://mindprod.com/jgloss/javadoc.html#TAGS

>From the DHIS2 perspective, the guidelines we have for style are here (
http://208.76.222.114/confluence/display/DOC/Code+Conventions#CodeConventions-Authorandversioninformation)
which states that the following:

--snip-begin--
Add the following before the first class/interface declaration in every
file, using your own name. Also, make sure you enable the $Id$ keyword in
Subversion.

/**
 * @author Example User
 * @version $Id$
 */

--snip-end--

We do need to rethink this a little.  @author is clear enough - it refers to
the original creator of the file.  The $Id$ tag is meant to be expanded to
potentially useful version information using version control systems like
CVS and Subversion.  See
http://208.76.222.114/confluence/display/DOC/Subversion+configuration#Subversionconfiguration-keywordsto
see what subversion does with the tag when configured to do so.

Also see for example our own javadoc.  Here's a file documented by Lars:
http://hispkerala.org/dhis2/apidocs/2.0.2/org/hisp/dhis/dataelement/DataElement.html

You can see has used $Id$ and subversion has expanded it to:
$Id: DataElement.java 5540 2008-08-19 10:47:07Z larshelg $

But we are not using subversion.  We are using bazaar.  And svn:keyword
expansion is not supported by default.  And in fact by design if you read
http://jam-bazaar.blogspot.com/2008/07/last-week-in-bazaar.html.  There has
been some plugin written for keyword expansion on bazaar but I don't know
much about it.  There are strong views against it in the bazaar community.

So we need to decide ourselves on what "best practice" to adopt and update
our style guide.  Jo, this sounds like something you would have an opinion
on.  Bearing in mind that the javadoc is for users of the class - it is not
a version control system.  We already have that developer information
elsewhere (bzr log).  And I am sure Saptarshi has an opinion which I can
almost guess from here ...

But going back to your original question of what to do with your new class
with:
*/**
 * @author Dang Duy Hieu
 * @version $Id: ABC.java 2009-09-18 17:20:00Z someone$
 */*

I think I can now give you an answer.   On @author you, as the creator of
the new file+class, should put your name (that is assuming that you have the
right to do so, but we've been through that - in dhis2 code you would have a
copyright notice further up in a comment anyway).  And for @version you
should just have "@version $Id$" until we revise our style guidelines.  You
definitely don't want to be manually hacking the $Id$ expansion.  And we
should revise our style guidelines.  Or decide to use bazaar to somehow
expand the tags.

And all of the above is assuming that it *really* doesn't make sense to
reuse the existing class in some way.  And I am not yet convinced without
seeing the classes that if there is a familiarity in form, there isn't some
relationship to make.  Even if it means refactoring both.

Regards
Bob

2009/10/5 Hieu Dang Duy <hieu.hispvietnam@xxxxxxxxx>

> Dear all,
>
> We are mixing two related but not the same issues.
>>
>>
> To avoid the mixing of copyright issue that why I thought I should have the
> question as a above one.
>
>
>> I don't think the case you describe is necessarily related to copyright.
>> I think we are assuming that you have the right to do what you need to do
>> and it seems your question is more one of  attribution.  If you are copying
>> a class over which you have not been granted licence that is a different
>> issue.
>>
>>
> Bob, thanks for your advice! I think we should not worry about the granted
> licence here because the example above file as ABC.java, which is a
> presenting file, was created by my colleagues. And then I just copied or
> make a clone of it to modify the new one it as my way.
>
> I thought all of you would have a question for me is that "Why have you to
> do that ?"
> It is very simple to answer this question. Because I have a reason for
> explanation with follow:
>
> I did not extend the original file to inherit its properties or methods
> because the original file can not resolve absolutely my problem as same as
> the cloned one - which has been modified following my way - though they are
> the same of structure and meaning.
> *
> *We could understand and image like the way of somehow saying about "*The
> FORM was not changed but The CONTENT should have changed*".
>
> I think Lars' suggestion is absolutely the correct one.  If you want to use
>> the class with its content absolutely unmodified then the preamble (the
>> @author and @version tags) should be left as it is.  Otherwise extending the
>> class is almost always the best solution.  If you feel yourself doing much
>> copying and pasting you should start to feel a little voice in your head
>> saying that you are probably doing the wrong thing.
>>
>>
> So, I am still not clearly understand about the *@author* and *@version*tags in this case.
> Whose name should I set to *@author* tag is my full name or the holder's
> name ? And how about the *@version* tag ?*
> *
>
>
>> Regards
>> Bob
>>
>> 2009/10/5 Brajesh Murari <brajesh2murari@xxxxxxxxx>
>>
>>>
>>> I have just got a mall question about the issue of Copyright
>>>>
>>>> If someone created a class *ABC.java* and then I copied it to another
>>>> one (*MYCLASS.java*) after that modifying anything without changing the
>>>> structure and meaning of the original file.
>>>>
>>>> So, what should I do with in the copyright line ?
>>>>
>>>> *For example*:
>>>>
>>>> */**
>>>>  * @author <SOMEONE NOT ME>
>>>>  * @version $Id: ABC.java 2009-09-18 17:20:00Z hieuduy$
>>>>  */
>>>> public abstract class MYCLASS
>>>>     implements Action
>>>> {..........................}
>>>> *
>>>>
>>>> Is it right, Lars ? Or I *must change like this:
>>>>
>>>> /**
>>>>  * @author Dang Duy Hieu
>>>>  * @version $Id: ABC.java 2009-09-18 17:20:00Z someone$
>>>>  */
>>>> public abstract class MYCLASS
>>>>     implements Action
>>>> {..........................}
>>>>
>>>>
>>>> *Thank you so much !*
>>>> *--
>>>> Hieu.HISPVietnam
>>>> Good Health !
>>>>
>>>>
>>>>
>>> I think it will be a better solution and good design pattern approach to
>>> use OOPS concept ie. Inheritance, specially if we make a subclass
>>> MYCLASS.java of class ABC.java rather then copying every thing from to
>>> ABC.java to MYCLASS.java. And this way we can handle copyright issue like
>>> this ...
>>>
>>> /**
>>>  * @author Dang Duy Hieu
>>>  * @version $Id: ABC.java 2009-09-18 17:20:00Z someone$
>>>  */
>>> public abstract class MYCLASS extends ABC
>>>     implements Action
>>> {..........................}
>>>
>>>
>>> This is one way to solve the issue but if ABC.java is final then .....no
>>> body can extend class ABC.java
>>>
>>> --
>>> Brajesh
>>>
>>>
>>>
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>>> Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>>> More help   : https://help.launchpad.net/ListHelp
>>>
>>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>> Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>> More help   : https://help.launchpad.net/ListHelp
>>
>>
>
> *Thanks to all guys !*
>
> --
> Hieu.HISPVietnam
> Good Health !
>