Understanding an API

Summarize the team's discussion for this part in a file called doc/COLLECTION_API.md within your team's project repository.

Although the concept is inherently subjective, most developers seem to agree on the main desirable characteristics of an API:

• Easy to learn
• Encourages extension
• Leads to readable code
• Hard to misuse

Each person should examine one of the following documents about Java's Collections API and discuss with the rest of the team how well the API follows the above characteristics:

• API vision
• API Design FAQ
• Package documentation
• General tutorial

Bring your own experience using collections by comparing them to the API's design goals. If there is something you like or dislike or something your learned about design during the discussion, make sure to back it up with a specific example.

Some things to consider:

• In your experience using these collections, are they hard or easy to use?
• In your experience using these collections, do you feel mistakes are easy to avoid?
• What methods are common to all collections (and why are Maps excluded)? What methods are common to all Deques?
• How many interfaces do specific concrete collection classes implement (such as LinkedList)? What is the purpose of each interface?
• How many different implementations are there for a specific collection class (such as Set)? Do you think the number justifies it being an interface or not?
• How many superclasses do specific concrete collection classes have (such as PriorityQueue)? What do you think is the purpose of each inheritance "level"?
• Why does it make sense to have the utility classes (such as Collections) instead of adding that functionality to specific collection types themselves (such as List)?
  • Are there any overlapping methods (ones that are in both a specific collection and a utility class)?
  • If so, is there any guidance on which one you should use?