[threeten-develop] Naming poll - LocalDate methods

[Stephen C. <sco...@jo...>]

The second question asked about the names of methods on LocalDate and similar.

The results were
Option A: 9.44% chose getYear(), getMonthOfYear(), getDayOfMonth(),
getDayOfYear(), getDayOfWeek().
Option B: 37.30% chose getYear(), getMonth(), getDayOfMonth(),
getDayOfYear(), getDayOfWeek().
Option C: 51.07% chose getYear(), getMonth(), getDay(),
getDayOfYear(), getDayOfWeek().
(Java experience level was a factor - those with mid-level experience
tended to be slightly more in favour of B with results of 13%/40%/44%)

The alternative responses included:
- public fields not methods
- abbreviations, such as getDayW
- getDayName for day-of-week
- omit the "get" part
- various suggestions of "missing" methods
- getDay() for day-of-week - note that this is the naming on java.util.Date

I wouldn't approve of abbreviations or public fields. The "omit the
get" ideas are interesting, however the get/with convention is very
easy to learn and a cornerstone of the design.

This question clearly suggests getMonthOfYear() would be preferred as
getMonth(), but the day-of-month question is more balanced, especially
when considered wrt how developers feel about the clarity of
"getDay()" as asked in other questions.

Stephen

Full list of alternate responses:
----------------------------------------
"Make Date immutable, have year, month, day etc. as public final fields"
"getYY(),getMM(),getDD(),getDD_YY(),getDD_W()"
"date.year(), date.isOnA(Monday),etc..."
now.getDayOfWeek()
"year(), month(), day(), dayOfYear(), dayOfWeek() get prefix is
unnecessary noise"
"year(), month() etc merged with the third option"
"getYear(), getMonth(), getDay(), getDayOfYear(), getDayOfWeek(), getWeekOfYear"
"getYear(), getMonth(), getDay()"
getDate()
"getYear(), getMonth(), getDay(), getOfYear(), getOfWeek()"
"getYear(), getMonth(), getDay(), getMonthOfYear(), getDayOfYear(),
getDayOfWeek()"
"getYear(), getMonth(), getMonthName(), getDay(), getDayOfYear(), getDayName()"
"getYear(), getMonth(), getDay(), getWeekday()"
"getYear(), getMonthOfYear(), getDayOfMonth(), getDayOfYear(),
getDayOfWeek(), getQuarterOfyear(), getQuarterStartDate(),
getQuarterEndDate()"
"same as option 2, eventually add internal Enum for a single
getDay(DayOf): getDay(DayOf.MONTH/YEAR/WEEK)"
unsure
"last option and getWeekOfYear"
"getYear(), getMonth(), getMonthName(), getDay(), getDayName(), getDayOfYear()"
"getDay() to get the day of the given date, and getDayOfMonth to get
the day within the given month. Also, similar methods with the today
prefix, for working with the current date."
"year(), month(), day(), dayofYear(), dayOfWeek()"
getToday()
"You know better than me :) if in doubt use joda-time names"
"perhaps getDayOf(DateUnit) ?"
"getYear(), getMonth(), getDayM() or getMonthDay(), getDayY() or
getYearDay(), getDayW() or getWeekDay()"
"getYear(), getMonth(), getDayOfMonth(), getDayOfYear(),
getDayOfWeek(), getWeekOfYear()"
"getYear(), getMonth(), getDay(), getDayOfYear(), getDayOfWeek(),
getWeekOfYear()"
getLastDayOfMonth()
"getYear(), getMonth(), getDay(), getDayOfMonth(), getDayOfYear(),
getDayOfWeek()"
"year(),month(),dayOfMonth(),dayOfYear(),dayOfweek()"
"getYear(), getMonth(), getDay(MONTH), getDay(YEAR), getDay(WEEK)"
year();month();day();week()
"year(), month(), day(), dayOfYear(), dayOfWeek() - set methods would
share name, but would have argument (e.g. java.nio.Buffer.{limit(),
position()} and similar in java.nio.*,
java.lang.ProcessBuilder.{command(), directory(), etc.},"
"getYearNoonUTC() etc. The world is inconveniently round, but a time
is absolutely meaningless without a timezone. Don't support the flawed
notion that it time has meaning without location. This will lead to
phenominal amounts of buggy code since most business folks (i.e.
project sponsors) don't get timezones and will try to tell programers
not to worry about timezones. Force the programmers to understand the
issue so that they can respond with appropriate and logical arguments.
The existence of such a class would be a detriment to Java's
reputation in the long run. Noon UTC will behave well everywhere but
perhaps midway etc. When it does misbehave it will be clear why it did
so. Do not foster the notion that timezone can be ignored."
"getYear(), getMonth(), getDay(), getDayOfYear(), getWeek()"