Papercut

A few weeks ago I got tired of finding comments like this in the codebases I work on:

// Remove this when it's not needed --Former Employee

Unfortunately, I don’t often have time to fix the issues mentioned in the comments as I encounter them. When I do have time, I don’t remember where the comments are.

In an effort to actually address this technical debt I created Papercut.

View Papercut on Github

Papercut is a library that provides annotations you can use in your codebase to mark items that should be removed or refactored.

@RemoveThis("Atrocious hack")
private void doSomethingStupid() {
    // Dumb code lives here
}

When you build your project the Papercut compiler will find your horrible code and fail your build.

You can add a date to the annotation if you know when you should be able to remove the offending code. Your build will work fine until the date you’ve chosen, at which point it will start to fail. This will force you to consider your tech debt and choose to do something, or nothing, about it.

@RemoveThis(value = "Fresh year, fresh start", date = "2017-01-01")
private void doSomethingStupid() {
    // Dumb code lives here
}

If you don’t know when you will be able to remove the code you can set the stopShip parameter to false, or switch to the @Refactor annotation to receive warnings instead of errors.

@RemoveThis(value = "Remove eventually", stopShip = false)
private void doSomethingStupid() {
    // Dumb code lives here
}

OR

@Refactor("Remove eventually")
private void doSomethingStupid() {
    // Dumb code lives here
}

You can set up @Milestones in your code and reference them in the @RemoveThis and @Refactor annotations. When you’ve reached a milestone you can simply delete it from your codebase. Any annotation that references the milestone will begin to fail or warn you.

@Milestone annotations can only be used on fields in your classes. I advise creating a Milestones class in your project, and using String constants to manage your milestones. This makes it less likely that you will make a typo, and your IDE will be able to identify all the places that were due to be refactored or removed when you delete the constant from your Milestones class.

public class Milestones {
    @Milestone("SOME_FEATURE") public static final String SOME_FEATURE = "SOME_FEATURE";
}

public class ThingDoer {
    @Refactor(milestone = Milestones.SOME_FEATURE)
    public void doTheThing() {
        // Dumb code lives here
    }
}

I hope that this library inspires you to tackle some of your tech debt.