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-keywords to 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:
__/**
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@gmail.com
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@gmail.com
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
- @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:
/**
__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
Post to : dhis2-devs@lists.launchpad.net
Unsubscribe : https://launchpad.net/~dhis2-devs
More help : https://help.launchpad.net/ListHelp
Mailing list: https://launchpad.net/~dhis2-devs
Post to : dhis2-devs@lists.launchpad.net
Unsubscribe : https://launchpad.net/~dhis2-devs
More help : https://help.launchpad.net/ListHelp
Thanks to all guys !
–
Hieu.HISPVietnam
Good Health !
