(Doc|Discussion): Document unmodifiable Collections
Open
chore
- Dominant language
- Java
- Stars
- 2k
- Forks
- 392
- Avg merge
- 11h 24m
- Merged PRs (30d)
- 36
Description
### Problem
In spoon we use at some places unmodifiable Collections (and some strange homemade implementations), but only some of the methods document their return type properly . This leads to program failures in downstream code if you don't expect it. Example: https://github.com/INRIA/spoon/blob/eac3535a6ffaa30db1beb829f7363a6f49f50e79/src/main/java/spoon/support/reflect/reference/CtIntersectionTypeReferenceImpl.java#L34
```java
/**
* Gets the bounds of the intersection type. Note that the first bound correspond to the current intersection type.
*
* T extends Interface1 & Interface2 // CtTypeParameterReference#getBoundingType == Interface1 and getBounds().get(0) == Interface1
*
*/
@PropertyGetter(role = BOUND)
List> getBounds();
```
The method documentation does not state it's an unmodifiable collection returned.
### Solutions
We have 2 possible solutions for this problem
#### Copy Constructor
We can simply return a new collection with methods like https://docs.oracle.com/javase/8/docs/api/java/util/ArrayList.html#ArrayList-java.util.Collection- , but have some performance overhead(never measured it to be fair)
#### Documentation
Add the unmodifiable behavior to the documentation. It's easier but then we have this behavior for ever if we don't want to break the method contract. Documenting can lead to some changes in our codebase if we have some interface implementations, that aren't returning unmodifiable Collections but must do it now. Can be even a breaking change in downstream code
What is your opinion on the 2 possible solutions? Do you have an other?
Contributor guide
Assessment
This issue has not been assessed yet.