*Dear Bob, * On Tue, Oct 6, 2009 at 8:46 AM, Bob Jolliffe <bobjolli...@gmail.com> wrote:
> 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. > > *It is really interesting in your reference documents. A good way which to be improved my own knowledge on this sense issue.* > 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. > > *Somehow in my mind I think I knew what I should do a little thing in my case.* > 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 > Really thank to all guys ! -- Hieu.HISPVietnam Good Health !
_______________________________________________ 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
