Quick question that just bit me, why does

TODO()

throw an

Error

instead of an

Exception

? The KDoc for

NotImplementedError

says: > An exception is thrown to indicate that a method body remains to be implemented. (It's extra weird considering

error()

throws an

Exception

)

It is an

Error

because it is a structural error in your code, not some exceptional condition from an external context/system.

I guess that makes sense. Still feels a little weird for some reason I can't place my finger on.

Broadly stated: • A Throwable is either an Exception or an Error. • An Exception can be a RuntimeException (although, all Throwables are unchecked in Kotlin)

Errors usually indicate something is seriously wrong with your dev environment or the way you’ve written your code. They are problems that should be fixed before trying to run your code again, as your program cannot work until you do. In this sense, errors are more akin to a compiler error than an exception, only that they’re detected at runtime. Thus, the library creators intended that the solution to a TODO isn’t to catch the exception and handle it. It’s to refactor your code so you’re not calling that method, since it’s clearly not ready for use.

Okay, that makes sense. I'm coming around to the idea. I think the KDoc I mentioned is wrong then. Should I file an issue, or do you all think it's okay as is?

What is wrong with the KDoc? If it is the word ‘exception’, it is not really wrong. Exception is a generic term (outside of Java as well) for something that a function can throw in an exceptional situation.

But

Exception

is not a generic term in this case. It's a specific class that is not part of the hierarchy of

NotImplementedError

.

Me being nitpicky 🙂: The word was written with a lower-case ‘e’… this indicates it being used as a generic term and not a class-name.

I see what you're saying, but that nuance in implied distinction can be confusing for native English speakers, let alone for those who speak it as a second language.