97 Things Every Java Programmer Should Know

Chapter 59. Name the Date

Kevlin Henney

As java.util.Date is slowly but surely deprecated into the Sun-set, with java.time taking up its mantle, it’s worth pausing to learn some lessons from its troubled life before letting it rest in peace.

The most obvious lesson is that date–time handling is harder than people expect—even when they’re expecting it. It is a truth universally acknowledged that a single programmer in possession of the belief they understand dates and times must be in want of a code review. But that’s not what I want to focus on here, nor is it the importance of immutability for value types, what makes a class (un)suitable for subclassing, or how to use classes rather than integers to express a rich domain.

Source code is made up of spacing, punctuation, and names. All these convey meaning to the reader, but names are where most meaning is carried (or dropped). Names matter. A lot.

Given its name, it would be nice if a Date represented a calendar date, i.e., a specific day…but it doesn’t. It represents a point in time that can be viewed as having a date component. This is more commonly referred to as a date–time or, if you want to put it into code, a DateTime. Time also works, as it is the overarching concept. Sometimes finding the right name is hard; in this case it’s not.

Now we understand what we mean by date, date–time, and Date, what does getDate do? Does ...