Spring can't decide how it wants to be configured

Spring framework has an identity problem.

For quite a while now, Spring has allowed Java Configuration to the extent that you can write a spring app without dealing with any xml at all.

Yet, if you were to look at the Spring Documentation today it would suggest otherwise. The documentation is littered with examples in xml code. While there are some examples of Java based configuration too, a person reading the documentation would come off with the impression that xml based config is the preferred way to use Spring.

If Spring wants people to keep their legacy XML configuration code, it should have the xml based config samples in the documentation as an addendum, not put it in the forefront.

For example Spring 3.2 introduced the AbstractAnnotationConfigDispatcherServletInitializer (long name i know, but its for a reason). Apart from a brief mention in ‘Whats new in Spring 3.2’, the documentation doesn’t incorporate it in the main documentation. So if you were not looking at the 'whats new’ lists for each release you probably wont know of a lot of cool features in Spring.

Contrast that to JavaEE documentation which consistently uses Java configuration and has no confusion regarding how it wants people to use it.

It doesnt end there…

This is not the only issue with the Spring Documentation. It seems other (highly popular) Spring projects cant decide on their documentation either. Take the example of Spring Data:

The Spring documentation says it uses Jakarta Commons Logging. You would assume the same to be true of Spring Data, especially since its documentation makes no mention at all of otherwise.

It is only when you start using Spring Data in your project, and run into a bunch of very weird errors, that you realize that it in fact uses SLF4J. And apart from asking on StackOverflow or looking into the sources there is no other way to confirm this.

Conclusion

Spring is an amazing framework, far better than JEE, and backed by a huge entity with commercial interests. But it needs to decide what is the one recommended way to configure Spring and stick to it. With all the cash they spend on evangelizing Spring, a bit more to get someone to write the documentation properly would benefit everyone.