I once worked maintenance on a large C++ program used in production by a lot of customers. It was odd in several ways, but the feature that stands out in my mind was the numerous classes that were not defined anywhere in the source code or libraries. If that sounds unlikely to you, it sounded unlikely to me, too. I wasted a lot of time trying to figure out where they were defined. I couldn't ask the original author o…
I have a simple rule about adding "magic" like that- if you can't make it immediately obvious to the readers of the code just what it is the magic is going to do, don't do it. AOP Java lead me to that rule because of too many obscure annotations that did insane things to help one developer avoid some minor nuisance.
Sometimes you have to get the job done in a "less than ideal" way. But a lot of documentation/comments should be left to justify and more importantly explain how it works.