Java Naming Standards – Are ‘Plus’ and ‘Minus’ Appropriate Method Names?

javamethodsnaming-standards

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.

Best Answer

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.

Related Solutions

Java Programming – When is Method Overloading Appropriate?

You overload when you wish to support different types:

public overload void MyMethod(int value)
{ 
}

public overload void MyMethod(bool value)
{
}

public overload void MyMethod(string value)
{
}

or to support a progressive interface using different parameter lists:

public overload void MyOtherMethod()
{
    this.MyOtherMethod(DefaultValue);
}

public overload void MyOtherMethod(int value)
{
    this.MyOtherMethod(value, DefaultOtherValue);
}

public overload void MyOtherMethod(int value, bool otherValue)
{
    ...
}

You might even get a little crazy and support both different types AND a progressive interface, but you should bear in mind that you need to avoid creating variations in behaviour between overloaded methods. Each overloaded method should be functionally the same as the others in an overloaded group, otherwise it will be unclear as to how, when or why behaviour is being varied. If you want two functions to do something completely different, then you should name them accordingly.

Java 8 java.time Classes – Missing getMillis() Method Explained

JSR-310 is based on nanoseconds, not milliseconds. As such, the minimal set of sensible methods are based on hour, minutes, second and nanosecond. The decision to have a nanosecond base was one of the original decisions of the project, and one that I strongly believe to be correct.

Adding a method for millis would overlap that of nanosecond is a non-obvious way. Users would have to think about whether the nano field was nano-of-second or nano-of-milli for example. Adding a confusing additional method is not desirable, so the method was omitted. As pointed out, the alternative get(MILLI_OF_SECOND) is available.

FWIW, I would oppose adding the getMillis() method in the future.

Best Answer

Related Solutions

Java Programming – When is Method Overloading Appropriate?

Java 8 java.time Classes – Missing getMillis() Method Explained

Related Topic