Traceability and entry points

Traceability is a kind of red carpet (or maybe green?) for learning to understand code. Ideally you can trace the code statically, by reading and ctrl-clicking calls. Polymorphism reduces traceability, but when used wisely, it's a very acceptable compromise. Inheritance also reduces traceability, but it's also difficult to use wisely :)

The second best form of traceability is dynamic: when debugging, you can trace even polymorphic method calls.

But, to be able to set break points for debugging, you need to know the entry points. The problem with typical enterprise code is that it has a lot of them, and you need to dig through a pile of XMLs and specifications to find them all. Even if you happen to have the container sources at hand, many calls are hidden behind reflection.

Tracing enterprise code statically is virtually impossible, but you can at least list all the entry points in one place. Create a documentation module that depends on all other modules and write an entry point document in Java. Just print the entry point classes/resources to stdout or something, and maybe even put some explanatory text in between. This file will be the only entry point for static tracing, verified by the compiler.

The long-term solution is of course to reduce the number of entry points. You don't have to use all those bells and whistles: just add one Plain Old Method Call instead of declaring an interceptor, for example. No more code needed (in fact, Java is even less noisy than XML), but a huge improvement on traceability.

Originally published on 2010-09-09 at under category Java