dhis2-devs team mailing list archive

[Hieu Dang Duy <hieu.hispvietnam@xxxxxxxxx>]

*Dear Bob,

*
On Tue, Oct 6, 2009 at 8:46 AM, Bob Jolliffe <bobjolliffe@xxxxxxxxx> 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 !