todo-or-die

"todo or not todo?", that is the ultimate question of life

About

A small Kotlin Multiplatform lib that helps you put off coding in a new, cool way, and reminds you to do your TODOs by throwing errors for your overdue tasks.

Please note that this project is in Alpha version. I initially created it to explore Kotlin Multiplatform, particularly publications of multiplatform libraries. At the same time the functionality is really primitive and "should work fine" (c) Famous Last Words.

Motivation

Have you ever found yourself in a situation when you develop a piece of software, that it is easier to hack something together to make it work, knowing very well that you can do a better job, but not taking the extra effort, and justifying it by saying "I can just fix it later"? Of course, you need to have some kind of reminder of what needs to be done and why (don't even get me started on "remembering things that need to be done"), so you add that infamous #TODO this is a temporary workaround, find a better way to handle this comment to your code, which will be that ultimate reminder for you to fix that "hack".

Or, while working on a piece of code, you spot something else in your codebase that should be fixed and/or improved, and use the same infamous #TODO Whoever wrote this piece of cr*p? Oh right, it was me. Refactor this nasty thing ASAP comment.

Unfortunately, while something along the lines of "fix it right away" might sound good on paper, in reality you can't always do that "fix" right away for various reasons. Another reality is, as LeBlanc's Law states, Later == Never, which has been proven time and again by numerous software developers and teams.

Installation

Gradle

Add the following repository to your build file:

repositories {
    maven(url = "https://dl.bintray.com/serpro69/maven")
}

Note that the project depends on kotlinx-datetime which is currently available only in the following repository: https://kotlin.bintray.com/kotlinx/

After the above repos are included in your build file, add one of the following to your dependencies:

//JVM
implementation("io.github.serpro69:todo-or-die-jvm:$version")

//JS
implementation("io.github.serpro69:todo-or-die-js:$version")

//MultiPlatform/commonMain
implementation("io.github.serpro69:todo-or-die:$version")

Latest releases of this lib are always available in this bintray repo.

Usage

It's quite simple really. Let's say you want to remind yourself to add some extra tests to your ControllerTest class.

By Date

The most common usage is to set a date for your TODOs:

class ControllerTest {

    init {
        TODO("2020-12-24") { // The due date after which an error will be thrown
            "Add a test for negative condition" // The description of your task
        }
    }
    
    @Test
    fun testHappyPath() {
        // some test
    }
}

The above piece of code will start throwing OverdueError from "2020-12-25" onward, which is probably a good example only if you want to get some angry calls from your management on the Christmas Day, but should still give you an overall idea on how to use the functionality.

Conditional ToDo

Another option is to provide a condition that returns true or false. An example could look something like this:

TODO("Upgrade to kotlin 1.5.0") {
    kotlin150IsReleased()
}

This will throw an OverdueError as soon as kotlin150IsReleased() function returns true.

"Won't this explode in my face at the most unexpected moment?"

Yes, it most definitely will if you forget to finish the task and remove the TODO. By no means am I encouraging you to use this in Production.

At the same time I find it quite useful to have during initial development and in testing, as well as in my OSS projects.

This also works quite nicely with TDD where you intentionally write crappy code initially just to make it work, and then refactor it later.

Nevertheless, I strongly recommend you to read what the default behavior of this lib does before it leads to you loosing your job. (Speaking of, please also take note of the lack of any guarantees and warranties in the licence)

Some failsafe configuration

You can configure your TODOs to not blow-up your code, but instead emit safe warnings like so:

TodoOrDieConfig {
    printCantDie = true
    messageLevel = Level.ERROR
}

With this, instead of getting those nice OverdueErrors you will have environmentally-friendly print-outs in your System.out.

Just like "Let's eat grandma" can mean two things, same applies to printCantDie property. As they used to say in the good old days: "Punctuation saves lives!"

The messageLevel simply changes the color of the output for the printed message, where available levels are:

• STACKTRACE - catches the OverdueError and prints the stacktrace from the exception object
• ERROR - prints the message in RED and prefixes with "[ERROR]"
• WARN - prints the message in YELLOW and prefixes with "[WARN]"
• INFO - prints the message in BLUE and prefixes with "[INFO]"
• DEBUG - prints the message in WHITE and prefixes with "[DEBUG]"

Contributing

Feel free to submit a pull request and/or open a new issue if you would like to contribute.

Licence

This code is free to use under the terms of the MIT licence. See LICENCE.md.

Thanks

• This project is inspired by todo_or_die ruby gem

• Many thanks to these awesome tools that help us in creating open-source software: