I’m finding I have a love-hate relationship with proxy objects, reflection and annotations.

For our project I need to build a module which is capable of serializing our Java objects over JSON. The specifics of our protocol are a little different than most, so I rolled our own parser. No big deal.

But then our requirements on what can be serialized changed; the server team wants to represent the objects passed to me by interface only. So I started playing with using annotations to mark the interfaces and classes that are serialized, and mark how they should be serialized.

It’s convenient: we can declare a class, sprinkle a few annotations in, and call it a day.

Which I love.

The part I hate, however, is that I’ve now, very easily, with just a few lines of code, created a specialized “meta-language” on top of the Java language to handle the serialization code.

And I despise meta-languages with a fiery hatred that could power a thousand suns.

The problem with meta-languages is that they violate the very notion of “discoverability” which is at the heart of code maintenance. No longer can you sort out the functionality of a class or an interface by looking at it’s declaration–now you have to also understand a domain-specific meta-language which alters the behavior of the those classes and interfaces in some hard to understand way.

Yes, I know: the solution to such a thing is documentation, documentation, documentation. I get that. And I certainly plan to spend more time on my documentation than I did adding the annotations in the first place, and putting plenty of references to that documentation in our code.

But there’s the problem: most programmers despise documentation. They think code should be self-documenting. (Which is another way of saying “I’m a damned lazy fool who is too stupid to recognize those shadows on my retinas as fellow co-workers.”) And so we wind up with very strange meta-language components that are impossible to discover doing tricky things that–without proper documentation–is impossible to understand.