File: PreferredInterfaceType.md

package info (click to toggle)
error-prone-java 2.18.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, forky, sid, trixie
  • size: 23,204 kB
  • sloc: java: 222,992; xml: 1,319; sh: 25; makefile: 7
file content (41 lines) | stat: -rw-r--r-- 1,570 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
Where possible, prefer referring to some types by a subtype which conveys more
information. For example: `ImmutableList` conveys more information (the
[immutability][javadoc] of the type) than `List`, `List` conveys more
information than `Collection`, and `ListMultimap` conveys more information than
`Multimap`.

This is consistent with [Effective Java 3rd Edition ยง64][ej3e-64], which says to
refer to objects by their interfaces.

*   Guava's immutable collection classes offer meaningful behavioral
    guarantees -- they are not merely a specific implementation as in the case
    of, say, `ArrayList`. They should be treated as interfaces in every
    important sense of the word.
*   Similarly, `Multimap` was designed as a superinterface for `ListMultimap`
    and `SetMultimap` which should [rarely be referred to directly][multimap].

That is, prefer this:

```java
ImmutableList<String> getCountries() {
  return ImmutableList.of("Denmark", "Norway", "Sweden");
}
```

to this:

```java
List<String> getCountries() {
  return ImmutableList.of("Denmark", "Norway", "Sweden");
}
```

TIP: Using the immutable type for the method return type allows Error Prone to
prevent accidental attempts to modify the collection at compile-time (see
[`DoNotCall`]).

[`DoNotCall`]: https:errorprone.info/bugpattern/DoNotCall
[multimap]: https://github.com/google/guava/wiki/NewCollectionTypesExplained#multimap

[ej3e-64]: https://books.google.com/books?id=BIpDDwAAQBAJ
[javadoc]: https://guava.dev/releases/21.0/api/docs/com/google/common/collect/ImmutableCollection.html