21

Java SE 8 comes with a new mechanism for dates, introducing LocalDate, LocalTime and LocalDateTime classes to represent instants of time. To manipulate such instants, a set of methods are given: LocalDate.plusDays(...), LocalDate.minusDays(...) and so on.

I've always thought that good practice was naming methods after verbs describing their purpose, as methods are, actually, operations to be executed, something that will perform an action. Just to mention, if you consider classes like StringBuilder, for instance, methods' names are append, insert, delete...

This is why to me it doesn't sound right naming a method plusDays instead of sumDays, minusDays instead of subtractDays. It's just me finding it very annoying? What do you think?

The only reason I can think of is that dates are immutable objects, so by calling plusDays you're not adding days to the original object but creating a new one with new properties, but that's very very subtle.

Improve this question
12
  • 22
    I think you're looking at this too technically. The actual goal for method names is to make it clear what it does and to make it readable. It just turns out that naming them with verbs normally accomplishes these two goals. However, consider a method called sqrt which takes the square root. Naming this method takeSqrt might seem to make sense according to your rule, but naming it this would not make the method more readable nor would it make it clearer.
    – Brandin
    Jun 9, 2015 at 12:26
  • 2
    Programming is not "English". For example, sqrt is just a word that programmers are expected to recognize and know. The English word is "square root" by the way. But naming things according to what is natural in English is not good. Take the word "illicit", for example, a perfectly fine English word. However, if someone named their method, say isIllicit I think I would want to tear out my eyeballs every time I looked at this method call. It just looks awful and there has to be a better way to express the idea.
    – Brandin
    Jun 9, 2015 at 12:56
  • 18
    sum sounds wrong in this context. I prefer .net's AddDays.
    – CodesInChaos
    Jun 9, 2015 at 15:54
  • 3
    @LuigiCortese The method names are chosen to match common English word ordering. Math.addExact(1, 2) because you say "add 1 and 2". tomorrow.plusDays(2) because you say "tomorrow plus 2 days". If addExact were a member of Integer somehow it would have been 1.plusExact(2).
    – Tavian Barnes
    Jun 9, 2015 at 16:28
  • 8
    Personally, I would expect plusDays to return a new date x number of days into the future, whereas addDays I might expect to mutate the original object. That's just me though, I'm not all that familiar with Java.
    – Ajedi32
    Jun 9, 2015 at 18:42

3 Answers 3

Reset to default
52

The only reason I can think of is that dates are immutable objects, so by calling plusDays you're not adding days to the original object but creating a new one with new properties, but that's very vary subtle.

This is exactly the reason. Imagine you had some kind of api for manipulating ranges of dates for scheduling purposes. It might expose methods letting you make a statement like:

var workdaySchedule = initialSchedule.withoutWeekends();

This reads very similarly to the English statement: "The workday schedule is the initial schedule without weekends". It doesn't imply changing the initial schedule, it implies the work schedule being a different, new thing.

Now instead imagine it was named:

var workdaySchedule = initialSchedule.removeWeekends();

This is confusing. Is initial schedule being modified? It certainly sounds like it, because it sounds like we're removing weekends from it. But then why are we assigning it to a new variable? Although these two naming schemes are very similar, this one is much less clearly evocative of what's happening. This would be more appropriate if removeWeekends did change the initial schedule, and returned void- in which case withoutWeekends would be the confusing option.

This is essentially a declarative vs. imperative distinction. Are we declaring that the workdaySchedule is a particular thing, or are we carrying out a list of imperative instructions (like "remove") to make that particular thing? Usually, imperative naming makes more sense when you're mutating values, and declarative makes more sense with immutable values, as the above example demonstrates.

In your case, you have exactly the same thing. If I saw: tomorrow.plusDays, I wouldn't imagine that tomorrow was being mutated, whereas tomorrow.addDays, I'd think it might be. This is somewhat subtle- but not necessarily in a bad way. Without having to think about it too hard, this naming naturally sets your thinking along the right lines in terms of whether or not you're mutating. To make this distinction between these imperative and declaritive styles clearer: "add" (and "remove") are verbs, whereas "plus" (and "without") are prepositions.

Improve this answer
6
  • 13
    I actually had a problem with addDays versus plusDays yesterday! In .NET, the DateTime class has methods called addDays, addMonths and addYears. I created method to parse out a relative date (1 year, 2 months, 3 days ago) and called the aforementioned methods thinking they were modifying the current DateTime object. Every date in the database ended up being June 8, 2015. "That's funny," I thought. That's when I remembered that addDays doesn't modify the DateTime object, it returns a new one. So +1's all around for this question.
    – Greg Burghardt
    Jun 9, 2015 at 12:17
  • 1
    @GregBurghardt As a .NET user, I have exactly opposite expectations. I guess this only means that "plus" and "add" are exchangeable, not direct mappings to + and +=
    – Agent_L
    Jun 9, 2015 at 14:25
  • 2
    @Agent_L That's interesting. .NET conventions aside, "add" and "plus" aren't interchangeable in English.
    – Ben Aaronson
    Jun 9, 2015 at 14:30
  • 1
    Also, for dates and times , it is sort of common to speak of D+1, H+12 and so on to reference time relative to a specific origin (also, for space flight T-10, T-9, etc). Commonly, this is read as D-plus-1, H-plus-12, T-minus-10. Maybe US centric, but that is how it appears to me.
    – Kristian H
    Jun 9, 2015 at 15:03
  • 4
    You might find this old StackOverflow question of Jon Skeet interesting: What's the best name for a non-mutating “add” method on an immutable collection?.
    – MicSim
    Jun 9, 2015 at 15:27
2

In .NET the naming is different although the result is exactly same. Instead of:

tomorrow = LocalDateTime.plusDays(1);

there is:

tomorrow = DateTime.Now.AddDays(1);

This only means that differences between understanding of "plus" and "add" ended up as matter of personal opinion. Cheer up, you're not alone, at least you can choose the language which appeals to you better : )

Improve this answer
-1

This is probably an artifact of Java using .Method for all methods, both those that modify the object and those that don't.

Imagine a language which also has a object=>method syntax, which would give method a copy of the object to work on. Now in such a language, startDate=>plusDays(5) is clearly unambiguous. It takes the original date, and creates a new date which is 5 days later.

On an unrelated note, sumDays doesn't make sense here. LocalDate is a time point, not a time duration. You can sum any number of durations (and the result is another duration), and you can add a time point and a duration (result is another time point), but you cannot sum time points.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.