ADR 7. Method Naming

Status

Status	PROPOSED
Created Date	2023-01-12
Decision Date

Context

We need to specify some method naming strategy for method-aliases in library.

What requirements:

• We need short, but meaningful names

• Try to keep naming as close as possible to Java Streams API naming

• Naming should be unambiguous

safe() - not necessary, any operation should be safe by default

toList() - not necessary because it’s default behavior

Any operation has name in Java Stream API (map, filter, flatMap)

if operation calls intermediate operation + collect() then keep in naming only intermediate operation and collector.

For example, method-alias for safeStream().map(…​).collect(toSet()) should have name mapToSet().

For collection result types:

Method Result Type	Class Name	Suffix
Stream<T>	Streams	toStream
List<T>	Lists	toList and without suffix
Set<T>	Sets	toSet
Map<K, V>	Maps	toMap
String	Strings	toString
T[]	Arrays	toArray
boolean	Matchers	without suffix
long	Counters	without suffix
T or Optional<T>	Finders	without suffix
void	Iterators	without suffix

intermediate operation + terminal operation / suffix

if > 1 intermediate operations concat them using And (e.g. filterAndMapToSet)

What if instead of collectToSet use just toSet? conflicts with standard java library.

Может нарисовать диаграмму принятия решения по неймингу?

What alternatives?

Decision

What is the change that we’re proposing and/or doing?

Make naming idiomatic (as it defined in Java) not to introduce new wording

The naming rules should be defined.

For Streams

• if intermediate operation presented add it to name

• if terminal operation presented use

• use suffix toStream

для разных классов свой нейминг

Может проще в decision обойтись советами по неймингу:

мол если можно опустить слово, опустите

• Имя должно подчеркивать суть

• Из имени метода можно понять что происходит внутри

• Для наиболее часто возвращаемого типа List<T> суффикс можно опустить.

• Любое поведение по дефолту можно не упоминать в нейминге (safeStream() call, toList by default, any input collection will be processed using stream, etc)

Иначе придется

The algorithm for pipelines with collect terminal operation:

• if intermediate operation presented use it else use collect

• Specify result type with to suffix (e.g. toSet, toMap, etc.)

For example:

return safeStream(collection)
        .filter(predicate)
        .collect(toList());

we have intermediate operation filter and result type is list

For example:

return safeStream(collection)
        .collect(toSet());

Use collectToSet().

Consequences

What becomes easier or more difficult to do because of this change?