Modern code if full of strong encapsulation of many small classes with many small methods. The theory is that such abstraction protects developers using those classes from the details of their internals and makes them easier and safer to use.

That only works where every level of encapsulation is thoroughly documented. In most modern code bases, the very encapsulation and abstraction that is promoted to protect users of the classes also serves to obfuscate how to use them.

Working backwards by reading the code works for small systems. Class A creates and instance of class B and calls a method to do something and that is as deep as the code is nested. Simples, as the meerkat promotion would say.

Descending into the rats nest

But what happens when the nest of classes gets more complicated? What happens when the code base gets bigger and we get away from simple inheritance into factories, facades, and all the clever ideas that have escaped from the bio-hazard vat in the corner of a computer science lab?

Class A creates an instance of class B, sometimes having to use class C to do that because it injects D, E and F into B. B doesn't really do anything except try to hide a bunch of further complexity by wrapping interfaces G and H with one liners into I, J and K.

The curse of meaningful names

All of these classes and methods have 'meaningful and descriptive' names. Except because they all do nearly the same thing, those meaningful and descriptive names are nearly the same and never distinct enough to be much help in working out what is really happening. They may have meant something to the developers at the time, but for those of us reading it afterwards, a lot of it is hopeful guesswork. The few minimal comments are limited to some @var lines that state the obvious without adding any real value and were probably generated by an IDE in the first place - the original developers never actually dirtied their hands by writing comments.

The obfuscation repeats and we dig our way through the alphabet to what is actually going on somewhere in Z. Except sometimes what happens is actually in X or Y, which look very similar to Z, and no can work out why. All of this is in the name of flexibility because this gives users the chance to substitute any of M, N, O or P for L should we need to in the future. But if anyone has ever needed to do so there is no record.

Digging up the ruins

Working out what is going on by code archaeology has become a modern developers burden amongst a cryptic mess of code. Even the best IDE can only work back so far through obfuscated references before giving up with a nervous breakdown.

Is it any wonder that too many developers create their own solutions rather than using what is already there. After all, if there are already 42 different open source products doing the same thing, why not develop solution number 43?

If the success of any project is measured by how widely it is used, the way to get there is to spend more time enabling others to use it and less time on the latest fashion in clever code.