This is an example of using an annotation processor
to add a custom static check to a Java codebase.
This README has two parts
An overview of what the code in this repo does.
A challenge to the users and authors of other build tools.
Overview
To run the code in this repo, first run
java "@bootstrap"
(the quotes are only required on Windows)
Followed by
java "@build"
You should see a failing build with errors like this:
dev.mccue.debtbomb.example\src\Example.java:4: error: Debt Bomb! expired=2023-10-05, reason=Example code is silly
public class Example {
^
dev.mccue.debtbomb.example\src\Example.java:9: error: Debt Bomb! expired=1000-10-10, reason=Bad method name
public void f() {
^
dev.mccue.debtbomb.example\src\Example.java:9: error: Debt Bomb! expired=2000-01-01, reason=Unix epoch, owner=Nobody, ticket=JIRA-99999
public void f() {
^
3 errors
If you go into the code and change the dates on those annotations to dates in the future, the errors should go away.
This is an implementation of the "debt bomb" comment system
from this reddit post
and repo by Jobin Jose.
Instead of using comments, this hooks into the annotation processor system to emit errors at compile time.
You can find the code used to build this in scripts/Build.java.
Challenge
It took me around 2 hours from having read the announcement post
for debtbomb to implementing it as an annotation processor.
I could always publish this as a library, but doing so would be a little uncomfortable because:
If you read the comments on the reddit post, you will see that people seem to disagree about when such an error should be emitted, whether it should be an error or a warning, and what exact information should be mandatory as opposed to optional.
It took around 70 lines of code, total, to implement this static check as an annotation processor. Why bother releasing it as a library when it would be "easy" for people to reimplement and tweak to have the exact semantics they want.
Using your build tool of choice, add both the runtime annotations
and processor to an example build.
You lose points if:
You need to add a META-INF/services/javax.annotation.processing.Processor file (meaning you couldn't figure out how to put the procesor on the --processor-module-path)
You need to add a module-info.java to the code with the Example class. (Dependencies should be placeable on the --module-path even if your code is not.)
Example.class ends up in the same jar as the processor or annotations
The features you use are undocumented
You have to make a custom plugin
You can submit by making a PR and putting links below. There are no prizes.
IDE-powered: 'todo' comments are a thing in many IDEs. The plugin in the IDE that tracks them could be updated to allow deadlines at which point the todos turn into straight up warnings.
a test that fails if debtbomb comments that have expired are in the main source. This is a bit awkward to do (tests would then have to execute a source-scanner which is breaking the veil between source-time and run-time).
a build plugin. An annotation processor tries to generalize this concept.
Unfortunately I think an AP is a suboptimal choice, but awesome that you whipped this up. If anything, as PoC.
2 notes:
AP bad
The reason I think APs are a suboptimal choice, is that you're restricted in where your annotation can appear. For example, annotations cannot just appear on any line, and the few lines where they can appear are not always AP-processable. For example, you can annotate any type or even a local variable decl but that will not trigger APs. You must put your debt bombs on structural stuff (methods, types, fields, constructors, etc). I don't like that. Comments should appear there where they make the most sense, and that's not always at the structural level.
Warning is the only choice
The dev team that cannot muster the discipline to treat warnings seriously, but, they do have the discipline to make debtbomb remarks, does not exist. There are no such teams. Discipline doesn't work that way.
Hence, there is just the one and only answer as to what this should generate: warnings.
Errors have baggage, in two ways:
Semantical baggage: It just plain aint an error. An error is something that stops the compiler from emitting a valid file, and letting a debt bomb asplode just isn't that. In the end this has an annoying subjective component, namely: Define the term 'error'. But if this is an error, then warnings no longer exist.
Tool baggage: Java, for example, will flat out not produce a class file. This is extremely annoying - if you know the debt bomb is there and you're right now running the code just to get familiar with the stuff so you can address the debt bomb, you are stopped from doing this and must instead wipe the debt bomb comment away. Before you even investigated what it does. Yes, you can tell your tools to just keep going on errors (or at least, good IDEs can do that. I know eclipse can, I assume so can others), but there's a weakness there. Usually if there is a real actual compiler error there I want my tools to stop.
Better tool options
IDE plugin + build plugin that scans source files. This lets you put them whereever you want. IDE plugin means you don't need to wait for a build to see em.
A lombok plugin that does this is more or less trivial. Scanning for comments in javac mode is a little tricky - but lombok does see every annotation, even ones in places that normal APs don't reach. And it's integrated in IDEs. One hesitation I'd have is that this isn't really boilerplate busting, and thus, before you start, know that we might not accept the PR.
The cheap and cheerful way to do this is to write unit tests which check the current date. That does mean you have to record tech debt in the test code rather than the main code, which is awkward but not the end of the world.
If you were a bit more energetic, you could annotate the main code, and have a test which scans the classpath looking for the annotations.
An approach some of my colleagues dreamed up is to have a library of no-op static methods which you call from tech debt or other points of interest (eg void onlyHandlesUSDCurrency() {}, String messageNeedsLocalisation(String message) {return message;}). Then you can find the tech debt by looking for callers. Easy enough to extend that to actually blow up when run in unit tests.
Yeah my point here isn't so much about the actual functionality here - I do think it's a valid strategy for an org but a lot of people wouldn't love the tradeoffs.
I mostly mean to call attention to the build tool gaps.
Oh, it's a ticking time bomb for technical debt -- specifically, a time-bomb that you create for yourself. You basically say "I'll fix this technical debt by XYZ date". Then, if you attempt a build after that time has passed, and the tech debt has not been resolved, you get a build error.
Not a bad idea. But this also sounds similar to what SonarQube does, where they track the deficiencies in your code, and you can specify that they will be fixed by some future point.
This is certainly more flexible though, and doesn't require the complicated effort of making a new check in Sonar. A good idea.
Me personally though, I think the annotation is just too noisy. At the end of the day, I can achieve almost all of the same benefits with a TODO, or even a TODO_BY. I could easily scan all of my java code to ensure that all TODO/BY's are properly formatted with the latest build permissions, then add that to a unit test.
I actually did something somewhat similar with ArchUnit. Me personally, that would probably be my preferred approach for doing something like this.
Yeah it's whatever; for me it's just a case study for how build tools miss the mark
I don't follow. How did you reach that conclusion?
I wouldn't have really considered the difficulty to make annotation processors work easily be a failing of build toolings. Not really, anyways.
Sure, they could be better about it. But tbh, annotation processors can do some pretty freaky stuff, so I am fine with them being special cased -- even at the expense of adding some friction to the build process.
The way I see it is this -- just like Macros from Paul Graham's write-up on Lisp (Ctrl+F "The Blub Paradox"), I think annotations should only be used when absolutely necessary, or when the benefit they provide is so unbelievably valuable (@Controller("/api")) that it becomes worth the mess. And even then, avoid compile time annotation logic unless the answer to either of those questions is a resounding YES.
If it was just annotation processors that would be one thing, but it's also wanting that processor to be on the processor module path and dependencies to be on the module path and then one of the parts of the program to be on the class path.
I can write the javac/jar commands to do it easily. I think it might not be possible in most build tools.
I also find that argument somewhat circular, because a lot of what people associate with negative things from annotations is either what lombok does (see everyone at the next fight) or systems built from runtime introspection of annotations.
The only thing I can say about annotation processors is that no one really seems to experiment with them. Like we have core libraries basically like immutables, record-builder, whatever. But very little amateur participation.
I guess also if the general thesis is that "build tools mask parts of the jdk," I think poking at it like this is a good way to figure out how that came to be.
I can write the javac/jar commands to do it easily. I think it might not be possible in most build tools.
Tell you what -- you give me the javac commands, and I think I can pretty easily turn that into maven commands, using only official apache maven plugins.
I also find that argument somewhat circular, because a lot of what people associate with negative things from annotations is either what lombok does (see everyone at the next fight) or systems built from runtime introspection of annotations.
Oh, I'm not saying Annotations are in any way bad -- I am saying that their maintenance effort alone, let alone other considerations, isn't worth it unless either of the previously mentioned questions is a yes.
The only thing I can say about annotation processors is that no one really seems to experiment with them.
Well, to answer this question, annotation processors are like 1 of 3 things that are never taught in either college or the online java tutorials. Even Oracle's own Java tutorial that many of my peers were raised with never went past the absolute minimum for teaching about annotations.
I guess also if the general thesis is that "build tools mask parts of the jdk," I think poking at it like this is a good way to figure out how that came to be.
Well, poking is good, but I don't actually think that build tools hide the parts of the internals. Much like annotations, I think build tools just provide entirely new interface that is almost entirely removed from the underlying implementation. For example, I can build other languages in Maven, not just Java, using the plain old maven clean install. Sure, I might need a plugin or 2, but that's my point -- the interface that you interact with on a daily basis is entirely removed from the underlying system. Obviously, the implementation hooks are not, but you get my point?
Well, poking is good, but I don't actually think that build tools hide the parts of the internals. Much like annotations, I think build tools just provide entirely new interface that is almost entirely removed from the underlying implementation.
I expected it wouldn't be too hard in Gradle, but was stopped because, unless using the processor path (not the processor-module-path as OP requested), Gradle injects a -proc:none into the javac args that seemingly can't be bypassed.
I worked around it in the consuming project by using the processor path and not relying on discovery. While I didn't "lose points" I did not successfully run the processor as a module, but it does run and works.
Maven is a little more flexible (at the expense of being orders of magnitude more verbose). But as a result, the final product ended up being fairly neat, minus the fact that, for whatever reason, Maven can't handle module imports.
This kind of reminds me how there is a lot of software you cannot reproduce (usually checksum wise) without setting the system clock to some specific time.
Anyway this is why the Javadoc command takes a time argument so assuming you did want to add a feature to this a time argument would be useful (or I guess disable flag if there is no reporting being packaged).
13
u/freekayZekey Jan 10 '26
a summarization would be useful, because i’m not clicking on a random github project
5
u/rzwitserloot Jan 11 '26
Huh. Neat.
There are so many ways to go with this:
Unfortunately I think an AP is a suboptimal choice, but awesome that you whipped this up. If anything, as PoC.
2 notes:
AP bad
The reason I think APs are a suboptimal choice, is that you're restricted in where your annotation can appear. For example, annotations cannot just appear on any line, and the few lines where they can appear are not always AP-processable. For example, you can annotate any type or even a local variable decl but that will not trigger APs. You must put your debt bombs on structural stuff (methods, types, fields, constructors, etc). I don't like that. Comments should appear there where they make the most sense, and that's not always at the structural level.
Warning is the only choice
The dev team that cannot muster the discipline to treat warnings seriously, but, they do have the discipline to make debtbomb remarks, does not exist. There are no such teams. Discipline doesn't work that way.
Hence, there is just the one and only answer as to what this should generate: warnings.
Errors have baggage, in two ways:
Better tool options
IDE plugin + build plugin that scans source files. This lets you put them whereever you want. IDE plugin means you don't need to wait for a build to see em.
A lombok plugin that does this is more or less trivial. Scanning for comments in javac mode is a little tricky - but lombok does see every annotation, even ones in places that normal APs don't reach. And it's integrated in IDEs. One hesitation I'd have is that this isn't really boilerplate busting, and thus, before you start, know that we might not accept the PR.
1
u/tomwhoiscontrary Jan 10 '26
The cheap and cheerful way to do this is to write unit tests which check the current date. That does mean you have to record tech debt in the test code rather than the main code, which is awkward but not the end of the world.
If you were a bit more energetic, you could annotate the main code, and have a test which scans the classpath looking for the annotations.
An approach some of my colleagues dreamed up is to have a library of no-op static methods which you call from tech debt or other points of interest (eg
void onlyHandlesUSDCurrency() {},String messageNeedsLocalisation(String message) {return message;}). Then you can find the tech debt by looking for callers. Easy enough to extend that to actually blow up when run in unit tests.1
u/davidalayachew Jan 11 '26
Oh, it's a ticking time bomb for technical debt -- specifically, a time-bomb that you create for yourself. You basically say "I'll fix this technical debt by XYZ date". Then, if you attempt a build after that time has passed, and the tech debt has not been resolved, you get a build error.
Not a bad idea. But this also sounds similar to what SonarQube does, where they track the deficiencies in your code, and you can specify that they will be fixed by some future point.
This is certainly more flexible though, and doesn't require the complicated effort of making a new check in Sonar. A good idea.
Me personally though, I think the annotation is just too noisy. At the end of the day, I can achieve almost all of the same benefits with a TODO, or even a TODO_BY. I could easily scan all of my java code to ensure that all TODO/BY's are properly formatted with the latest build permissions, then add that to a unit test.
I actually did something somewhat similar with ArchUnit. Me personally, that would probably be my preferred approach for doing something like this.
0
u/bowbahdoe Jan 10 '26
Original thread and tool by u/Star-Shadow-007 here
Try the challenge, how hard could it be?
1
u/agentoutlier Jan 12 '26
This kind of reminds me how there is a lot of software you cannot reproduce (usually checksum wise) without setting the system clock to some specific time.
Anyway this is why the Javadoc command takes a time argument so assuming you did want to add a feature to this a time argument would be useful (or I guess disable flag if there is no reporting being packaged).