Tracking hacks is hard. There are a few static analysis tools like PMD and SonarQube that help us identify and categorize tech debt. However, such tools miss perfectly legal but “hacky” code. Consider the case of the “temporary variable”. The implementation was a result of a time crunch instead of inability to write good code. We have all been there, and I can be reasonably sure that we will be at the cross-roads again.

There is a need for something that will allow devs to:

  1. Write down justification for hacks in a programmatically consumable format
  2. Assign a tracking ticket or at least link to a future work item
  3. A forcing function that will help prioritize the removal of hacky code

I could not find something light-weight that satisfies all three requirements, so I ended up writing record-hacks. It is a Java library that will help you track “creative solutions” in your code. You can use it to document the rationale behind some questionable choices in your code as well an aspirational date for an intended fix.

This library provides:

  1. @Hack annotation
  2. A compiler processor that processes all instances of @Hack in your code.

Th @Hack annotation captures:

  1. [Required] A description of the hack.
  2. [Optional] A trackingUrl. A link or identifier to any bug tracking system that has an item to fix this hack, eventually, of course.
  3. [Optional] A fixByDate. Probable fix date for this hack i.e. this hack will be cause the build to fail after this date. At such time you either need to fix the issue and remove this annotation or update the date to sometime further in the future.

These annotations are will be discarded by the compiler after processing and will not be carried over to any class files.

Usage

Import the library

<dependency>
  <groupId>net.kumbhar.dx</groupId>
  <artifactId>record-hacks-annotations</artifactId>
  <version>1.0</version>
</dependency>

In your code

    @Hack(
        trackedBy = "https://example.com/PROJECT-1234",
        fixBeforeDate = "2019-12-31", /* Compilation will fail if this annotation is not removed after this date */
        description = "This is a hack that will make my life miserable soon"
    )
    public void hackyMethod() {
        // Hack implementation
    }

Source available on Github.

I am adding record-hacks to all my future Java projects. Hopefully that will reduce the number of long living creative solutions in my code.