Keep your codebase simple
Latest commit d8d2d85 Jan 9, 2017 @Stuie Squashed commit of the following:
commit 13eea7941f01d556fbf9f42eca750e56fd53cc89
Author: Stuart Gilbert <>
Date:   Mon Jan 9 21:03:15 2017 -0800

    Bumping version number to 0.0.4

commit 9e5d2b4
Author: Stuart Gilbert <>
Date:   Mon Jan 9 20:27:56 2017 -0800

    Fixing logic error

    Empty version name was leading to IllegalArgumentException because I wasn't dropping out before jsemver choked on it.
    Also removed some debug logging that slipped into the snapshot builds.

commit 715afb4
Author: Stuart Gilbert <>
Date:   Mon Jan 9 20:05:30 2017 -0800

    Use correct variable in condition checking

    versionName was using a field instead of a local variable.
    Some javadoc changes and additions

commit 1aa7ddb
Author: Stuart Gilbert <>
Date:   Mon Jan 9 19:35:16 2017 -0800

    Updated README to mention versionCode, bump version

commit fcaba6a
Author: Stuart Gilbert <>
Date:   Mon Jan 9 13:08:40 2017 -0800

    Exception handling for jsemver

    IllegalArgumentException and ParseExceptions are now caught and handled with a more useful error message than the one offered by jsemver's default. It should be easier to know what went wrong without having to enable the stacktrace for the build.

commit 6760dc6
Author: Stuart Gilbert <>
Date:   Mon Jan 9 09:56:55 2017 -0800

    Updated supported Java version for annotationProcessor

commit c6accaf
Author: Stuart Gilbert <>
Date:   Sun Jan 8 22:44:20 2017 -0800

    Adding in basic support for versionName

    Relies on the app using semantic versioning as in Support for this comes from
    Tidied up the dependencies a bit.
    Fixed a unit test now that two options can be passed.

commit 7d81dff
Author: Stuart Gilbert <>
Date:   Tue Dec 27 11:56:56 2016 -0800

    Initial versionCode support added

    Added mostly useless unit tests for AnnotationProcessor.
    Updated messaging to use String.format and use the relevant annotation name.

commit b32e558
Author: Stuart Gilbert <>
Date:   Mon Dec 26 20:51:26 2016 -0800

    Beginnings of versionCode support.


Keep your codebase simple.

  • Annotate parts of your code that shouldn't make it to production
  • Automatically fail your build
  • Remember to remove code you don't need

@RemoveThis and @Refactor

The @RemoveThis and @Refactor annotations can be used interchangeably, but a @RemoveThis will trigger a build failure by default, whereas a @Refactor will only trigger a warning.

class TemporaryHack {
    private static final boolean DEBUG = true;
class ThingDoer {
    @RemoveThis(date = "2017-01-01", value = "After SOME_FEATURE has launched")
    private void someHackyMethod() {
        // Here there be monsters

Your build will fail at compile time by default.

/Users/stu/workspaces/TestApp/app/src/main/java/testing/ error: STOP SHIP: @RemoveThis found at:
    private static final boolean DEBUG = true;
/Users/stu/workspaces/TestApp/app/src/main/java/testing/ error: @RemoveThis found with description 'After SOME_FEATURE has launched' at:
    private void someHackyMethod() {
2 errors
:app:compileDebugJavaWithJavac FAILED

If you set the stopShip parameter to false in the annotation then you will only receive a warning. This matches the behavior of Refactor.

@RemoveThis(value = "After SOME_FEATURE has launched", stopShip = false)
private void someHackyMethod() {
/Users/stu/workspaces/TestApp/app/src/main/java/testing/ warning: @RemoveThis found with description 'After SOME_FEATURE has launched
    private void someHackyMethod() {
1 warning

With a small modification to your build.gradle file you can use version codes or version names instead of dates in your annotations.

In the case of an Android app, you can pass your version code and name to Papercut using the configuration below.

android {
    defaultConfig {
        versionCode 4
        versionName "0.4.0"
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = ['versionCode': String.valueOf(defaultConfig.versionCode),
                             'versionName': defaultConfig.versionName]

The arguments must both be passed as strings. The versionCode will be passed to Integer.parseInt() and the versionName must match the semantic versioning schema.

You can then use the versionCode or versionName parameters in your annotations as below.

@Refactor(versionName = "0.4.0")
private void fetchSomethingRemote() {
    // Temporary hack, please remove


You can define milestones by which you would like to refactor or remove code. When you reach a milestone just delete the @Milestone annotated field. If you use constants as in the first example below then deleting the field should cause your IDE to highlight the instances that referenced it. If you use plain strings in your @RemoveThis or @Refactor annotations then they must match your defined @Milestones exactly, as in the second example.

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

public class ImportantThingDoer {
    @Refactor(milestone = Milestones.LOGIN_REDESIGN)
    private void onlyUsedByLoginScreen() {


    @RemoveThis(milestone = "VERSION_2")
    public void callOldAPI() {


For full documentation and additional information, see the website.


dependencies {
    compile: 'ie.stu:papercut-annotations:0.0.4'
    annotationProcessor: 'ie.stu:papercut-compiler:0.0.4'

To use Papercut only in release builds you can alter the annotationProcessor line to use releaseAnnotationProcessor or debugAnnotationProcessor to suit your needs. Delaying the execution until you're trying to build your release version may be lead to unexpected build failures.

dependencies {
    compile: 'ie.stu:papercut-annotation:0.0.4'
    releaseAnnotationProcessor: 'ie.stu:papercut-compiler:0.0.4'


Copyright 2016 Stuart Gilbert

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

Snapshots of the development version are available in Sonatype's snapshots repository.