As part of the London Java Communities efforts to help out in JSR-310 efforts, we have been working with Stephen Colebourne to gather the feedback of the community on method naming conventions that would potentially be used in the upcoming implementation. After all, it is hoped that everyone in the Java world writing systems using dates will be potentially using the API from Java 8 onwards.

The intention of this blog post is to publicise the results and to encourage you to participate in the discussion. We are at the crossroads of finalising design and adapting the already comprehensive implementation to match the requirements. Please join us on the mailgroup and continue the discussion: mail group

There are 9 public questions that will be broken down into the general responses. The response has been immense, and behalf of everyone involved with the project I’d like to take this opportunity to thank you for your participation. The total number of surveys received was 1824. These results will contribute towards steering the API changes discussed on the mailing list.

The statistics below are summary statistics for the main categories, a full CSV of all anonymous responses is available here.

1. It is planned to have an enum for the month-of-year (January to December). What should this class be called?

  • 89.21% chose the format Month – eg. Month.APRIL.
  • 8.55% chose the format MonthOfYear – eg. MonthOfYear.APRIL.
  • 2.24% gave an alternate response.

2. There will be a class representing a date on its own (no time, or time-zone). Thinking about this class, what set of methods would you prefer to use.

  • 51.07% chose getYear(), getMonth(), getDay(), getDayOfYear(), getDayOfWeek().
  • 37.30% chose getYear(), getMonth(), getDayOfMonth(), getDayOfYear(), getDayOfWeek().
  • 9.44% chose getYear(), getMonthOfYear(), getDayOfMonth(), getDayOfYear(), getDayOfWeek().
  • 2.19% gave an alternate response.

3. Thinking specifically about getDay() vs getDayOfMonth(), which of these statements do you agree with? (This was a select multiple question)

  • 23.81% chose if I saw getDay() I would assume it was day-of-month.
  • 20.33% chose I would quickly learn that getDay() meant day-of-month.
  • 19.88% chose while it is longer, getDayOfMonth() is a lot clearer.
  • 16.63% chose getDay() is not clear without reading Javadoc.
  • 15.83% chose getDayOfMonth() is too long.
  • 3.52% gave an alternate response.

4. There will be a class representing a time-of-day on its own (no date, or time-zone). Thinking about this class, what set of methods would you prefer to use?

  • 72.44% chose getHour(), getMinute(), getSecond(), getNano().
  • 13.30% chose getHour(), getMinute(), getSecond(), getNanoOfSecond().
  • 8.04% chose getHourOfDay(), getMinuteOfHour(), getSecondOfMinute(), getNanoOfSecond().
  • 6.23% gave an alternate response.
5. The month-of-year can be represented as both an int and as an enum. How should method access to this be achieved?
  • 58.29% chose only have a method returning the enum, with the int value available via a method on the enum.
  • 12.31% chose getMonthValue() returns an int; getMonth() returns an enum.
  • 8.11% chose getMonth() returns an int; getMonthOfYear() returns an enum.
  • 7.08% chose only have a method returning the int, removing the enum from the API.
  • 7.08% chose getMonthInt() returns an int; getMonth() returns an enum.
  • 3.91% chose getMonthOfYear() returns an int; getMonth() returns an enum.
  • 3.22% gave an alternate response.
6. What factors should drive the method naming choice?
Question
Agree: 1
2
3
4
5: Disagree
Not sure
#
6.1 Shortest possible 20.45%

(346)
 22.75%

(385)
 21.28%

(360)
 13.71%

(232)
 19.03%

(322)
 2.78%

(47)
 1692
6.2 Pattern based 31.36%

(519)
 32.51%

(538)
 16.19%

(268)
 4.95%

(82)
 2.05%

(34)
 12.93%

(214)
 1655
6.3 Clear when read 65.61%

(1139)
 23.33%

(405)
 6.05%

(105)
 4.09%

(71)
 0.23%

(4)
 0.69%

(12)
 1736
6.4 Verbose 7.61%

(125)
 13.40%

(220)
 28.38%

(466)
 22.41%

(368)
 21.56%

(354)
 6.64%

(109)
 1642
6.5 Unambiguous 44.14%

(746)
 29.64%

(501)
 15.86%

(268)
 5.27%

(89)
 2.37%

(40)
 2.72%

(46)
 1690
6.6 Quick to write 17.15%

(286)
 23.14%

(386)
 26.92%

(449)
 16.91%

(282)
 13.37%

(223)
 2.52%

(42)
 1668
6.7 Consistent 64.57%

(1099)
 23.80%

(405)
 6.17%

(105)
 3.53%

(60)
 0.41%

(7)
 1.53%

(26)
 1702
6.8 Balance of short and clear 48.93%

(823)
 27.35%

(460)
 14.15%

(238)
 5.35%

(90)
 1.84%

(31)
 2.38%

(40)
 1682
6.9 No need to read Javadoc 32.15%

(542)
 30.72%

(518)
 20.94%

(353)
 9.13%

(154)
 4.63%

(78)
 2.43%

(41)
 1686

7. Too large to publish easily in the blog.

8. Have you used Joda-Time?
  • 41.48% chose never.
  • 36.34% chose occasionally.
  • 22.18% chose frequently.

9. How much experience do you have with Java?

  • 69.95% chose more than 5 years.
  • 22.94% chose 2-5 years.
  • 4.62% chose less than 2 years.
  • 2.48% chose Java is not my main language.