During JavaOne 2014, I suddenly realized I was talking with Collin Fagan, who has been of great help to me over the years via his blogs and articles relating to Java Swing development, such as this one. We were chatting at the end of Werner Dietl's BOF on type annotations, where I had presented some experimental work done in this area by Jan Lahoda for NetBeans IDE. More on that another time.
However, Collin mentioned his idea of a @Hack annotation. Often, when you're creating a library or framework of some kind, you're aware that your users will be using or implementing some kind of hack that you haven't had the time to clean up. You're going to come back to it later, in a future release. In the meantime, it would be pretty handy for the user of your code, i.e., another developer building on top of your library or framework, to know that they're using or implementing a hack. And, for you yourself, it will also be handy to know where to go to find your own hacks. Sure, you could add that info to the javadoc or use 'todo' comments, but it would be far more effective if you'd be able to annotate your method with a specific annotation, which could then be used by tools, such as NetBeans IDE, for code analysis, e.g., how many hacks have you, as the user of the library or framework, used or implemented? And to what extent does the library or framework you've spent years working on hang together precariously by means of a series of interconnected hacks?
Let's say for example that you're either using or implementing the Printer class above and you see hints in your IDE, such as this:
That's pretty useful. Even better than a hint would be editor annotations, i.e., a special icon in the left sidebar that marks hacks that you're working with.
Then various actions can be performed throughout your source code, e.g., search through all your applications for work you're doing with other people's hacks:
And then you'd see throughout your code where the hacks are being used.
A further enhancement could be to enforce a "reason" attribute in the annotation, so that the provider of the hacked code would need to explain in a few words why the hack is a hack and what the impact might be, e.g., performance problem or reflection code used, or something like that.
Pretty useful! It implies, though, that authors of libraries and frameworks need to be honest about their hacks. In fact, I'm calmly waiting to be excoriated for suggesting that (1) hacks exist in production code or (2) that an annotation such as this one would encourage hacks. More than likely, I'll be flayed alive in public for both. Should you be one of the flayers-to-be, please include a reference to your GitHub repo.
Note: For those wanting to see the implementation of the @Hack annotation... well... it's kind of... hacked together... at the moment.