Hi John,
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.
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.)
> 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 */? 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?
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?
> As always, there is a limited amount of hours in the day and decisions must
> be made on where to spend that time.
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?)
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.
Greg
On May 16, 3:48 pm, "John A. Tamplin" <j...@google.com> wrote:
> On Monday, May 16, 2011 1:22:43 PM UTC-4, Greg Dougherty wrote:
>
> > It's too bad that there a 2 valid comments, and 34 worthless ones.
>
> > Might I suggest that the GWT "Coding Standards" would do well to focus
> > on requiring people to write readable and understandable code (which
> > means having comments that explain what you're doing and why), rather
> > than merely obsessing on whether people use tabs or spaces?
>
> See the TODO at the beginning of PredefinedFormat -- patches welcome.
>
> The *_{SHORT,MEDIUM,LONG,FULL} formats are harder to describe the other
> formats like the ISO_8601 and RFC_2822 formats, since they will vary
> significantly across locales. Basically, for these we just use whatever
> those are defined as in CLDR. AFAIK, there is no documentation on exactly
> what the criteria are for those lengths, which means the Javadoc that would
> go there would be either "A short date format" or "The CLDR short date
> format", which doesn't seem more useful than the name itself which is why it
> hasn't been written yet.
>
> 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"?
>
> Regarding the overall quality of doc in the GWT codebase, my personal
> experience is that it is far better than most open-source projects -- of
> course it can always be improved and anyone can submit such improvements.
> As always, there is a limited amount of hours in the day and decisions must
> be made on where to spend that time.
--
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.
