On Tue, May 17, 2011 at 12:39 PM, Greg Dougherty <dougherty.greg...@mayo.edu
> wrote:
> Actually, I must entirely disagree with you. "The CLDR
> {SHORT,MEDIUM,LONG,FULL} format, as defined here (give URL to the
> definition)" would be a perfectly valid comment. Most importantly, it
> would tell users where to go when they need more information, rather
> than requiring us to guess.
>
Well, if you want the definitions for each locale, there are 587 of them.
As I mentioned, I am not aware of any documentation inside of CLDR that
describes generally what these formats mean, other than the obvious
relationship based on the names. For example, en.xml and fr_BE.xml are just
two of them. If you want a general description describing the sorts of
formats will be used across all the locales, well, that is why it hasn't
been written -- it would take a fair amount of time to go through all of
them and try and extract the commonalities.
> Now, it would be nice if you included that it was locale specific, or
> what some useful date (like Jan 5, 2002 (month name w/ more than three
> characters in it, month, day and year w/ only 1 significant digit when
> in 2 digit format) looked like under the format if it isn't locale
> specific. But if you don't want to write in all the details, telling
> users exactly where to go to find the details is a perfectly valid
> second choice. (Note that means a URL that gets the user to the
> definition of interest. Saying "go to the W3C specification" doesn't
> count. Since you were presumably looking at the specification of
> interest while writing the constant, I don't think it's unreasonable
> to expect you to pass on that specific URL.)
I really think you don't understand where this data comes from. The links
above give just two of the CLDR source files -- if you want to see the GWT
code that is derived from them, look at all the
DateTimeFormatInfoImpl_<locale>.java files, dateTimeFormatShort methods.
The point is that I can't tell you the month name will be numeric or
abbreviated or full, because it is different in different locales. The
point is that DATE_SHORT is the best guess for a "short" format as
determined by expert volunteers for each locale.
> > The other predefined formats, which are also derived from CLDR data via
> > ICU4J, seem self-explanatory. Is there really much value in a Javadoc
> for
> > the HOUR_MINUTE_SECOND format that says "A format containing the hour,
> > minute, and second"?
>
> Is there really much COST to writing /** A format containing the hour,
> minute, and second, in the form hh:mm:ss */?
The point is that it isn't in the form "hh:mm:ss" -- it is locale-dependent.
What is common is that it contains the hour, minute and second, which
should already be clear just from the name of the constant.
> Especially considering
> that you had to write SOMTHING, or else there wouldn't have been a
> JavaDoc entry in the first place. If you're going to write something,
> why not take an extra 15 seconds, and write the right thing?
>
Personally, if the Javadoc provides absolutely nothing over the name of the
thing you are documenting, it is better to not include a comment saying the
same thing. To me, *that* is the definition of a useless javadoc comment,
and now there are two places you have to change when you update it and you
give opportunities for them to not say the same thing when they should.
> For that matter, doesn't Code Tools Pro default to putting the value
> of the constant in the auto-generated JavaDoc? If you can have some
> code generation tool generate a more useful comment for no effort, why
> spend person time to generate a less useful comment?
I have no idea what Code Tools Pro does, as I don't use it. How would this
add any value anyway?
/**
* DATE_SHORT
*/
DATE_SHORT,
I cannot agree that is an improvement.
Of course. But, ESPECIALLY in an open source project, there's no
> point in writing something unless people can use it. If you want
> people to use your code, they've got to be able to figure out what it
> does, and how they should use it. If you're not willing to document
> something well enough so that other people can use it, why are you
> wasting your time writing it in the first place? (This is not a
> rhetorical question. When I writing code that I want other people to
> use, I make sure that everything I want them to use is clearly
> documented. If the writers of open source code aren't writing code
> because they want other people to use it, why ARE they writing it?)
>
See above. I do not know a comment that could be quickly added that would
be more descriptive of what DATE_SHORT means than the enum name itself. I
agree it would be great to have one that succinctly and accurately described
it, but I don't have the time to go through all the CLDR formats and reverse
engineer out such a description (which would then have to be re-evaluated
each time CLDR was updated). In the absence of such a description that
would actually be better than the name of the enum, having no comment is
better than an inaccurate one.
> Personally, I don't use any of the PredefinedFormats. I don't
> understand them, and it wasn't clear to me that it would take me less
> time to figure them out, than it would take me to write my own. Were
> those formats written for internal GWT use only, and any external use
> considered gravy? Or were they written for GWT users to use them?
> Because if it's teh second, the JavaDoc is the most important thing
> about those constants. Since that's going to be the major deciding
> point WRT whether or not the constants actually get used.
>
If you don't want to use them, then don't. It seems plenty of
others<http://codesearch.google.com/codesearch?hl=en&start=0&sa=N&q=PredefinedFormat%5C.>figured
out how to use these formats, despite the lack of a Javadoc, and
that is just the open-source projects supporting only GWT 2.2+.
You can certainly put your own formats in your source and use them, but if
you care about users in non-English locales using your app then you will
want to use a different format for each locale. As a simple example, if you
use "M/d/y" as the format, many European users will be confused because they
expect "d/M/y" and will mix up the day and month numbers. Since you read
the Javadoc carefully, I am sure you saw the warnings in
DateTimeFormat.getFormat(String) explaining the issue and decided to come up
with your own localized patterns for all the locales, right?
--
John A. Tamplin
Software Engineer (GWT), Google
--
You received this message because you are subscribed to the Google Groups
"Google Web Toolkit" group.
To post to this group, send email to google-web-toolkit@googlegroups.com.
To unsubscribe from this group, send email to
google-web-toolkit+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/google-web-toolkit?hl=en.
