Why Does Java Hide So Much Behavior Behind Simple APIs and Annotations?

There’s nothing wrong with reading Java’s source code, and it can be a great way to learn. Still, source is not always the best first stop. Start with the API documentation, especially the method’s notes, exceptions, mutability guarantees, and thread-safety details. Methods such as Collectors.toMap also document their default behavior, including failures caused by duplicate keys, and provide overloads when you need a merge strategy. Framework annotations are similar: they are instructions to a container, so understanding the lifecycle and scope model is just as important as reading the class itself.

Annotations can make ordinary-looking fields and methods participate in a much larger runtime system. With dependency injection, scopes, pooling, proxies, and lifecycle callbacks, the source file alone may not describe the full behavior. The practical approach is to learn the framework’s core concepts, keep business logic in appropriately scoped components, and avoid relying on accidental implementation details. That is less about memorizing magic and more about understanding the rules of the runtime you are using.

Interfaces and polymorphism are part of the reason the concrete class is not obvious from the method signature. Returning List instead of a specific implementation gives the library freedom to choose an efficient representation, but it also means callers need to know which operations are supported. When an operation is essential, check the contract or create the kind of collection you actually need instead of assuming every implementation has the same capabilities.

A method’s interface usually tells you what you can rely on, but the documentation tells you the important behavioral details. Arrays.asList is a good example: its documentation explicitly says the returned list is fixed-size and backed by the supplied array. If you need a resizable list, make a copy, such as new ArrayList(Arrays.asList(array)). Treat the Javadocs as part of the API contract rather than assuming every List implementation behaves identically.

Some surprises are unavoidable in any mature language, but tests should catch cases like trying to resize a fixed-size collection. It also helps to distinguish the abstraction from the implementation: a List guarantees list operations in general, but individual implementations may have different performance and mutability rules. When those differences matter, document the expected behavior in your own method signatures or choose a more specific type and construction pattern.