API guidelines

[LVMVRQUXL]

💡 The idea

We would like to follow the official Kotlin guidelines for libraries.
Here's the list of points discussed for the next versions:

• Member and extension functions
• Inputs validation
• Avoiding variable number of arguments
• Avoid data classes in public API
• Avoiding infix keyword on operator function

🙏 Help needed

Please give this post a reaction if you are interested in this next version, or comment it below if you have any suggestion.
We would love to have your feedback!

[LVMVRQUXL]

Member and extension functions

Source : Readability chapter in Kotlin guidelines.

Like mentioned in the Kotlin guidelines, we should write only the core of the API as member functions and everything else as extension functions.
This means that the types provided by this library should only have properties, overrides and accessors as member functions.

For example, the AnyInt hierarchy should have the following core API:

/** Representation of all integers. */
sealed interface AnyInt {
    /** Returns this integer as an [Int]. */
    fun toInt(): Int
    
    /** Returns the string representation of this integer. */
    override fun toString(): String
}

As we can see in this definition of AnyInt, the core of its API includes the toInt function for accessing the underlying value and overrides the toString function for getting its string representation.

This design choice is linked with our Less is more principle in our design goals.

[LVMVRQUXL]

Inputs validation

Source: Predictability chapter in Kotlin guidelines.

As recommended by the Kotlin team, we should use the require function for validating inputs.
Here's an example for the Number.toNonZeroInt function:

sealed interface NonZeroInt

/**
 * Returns this number as an encapsulated [NonZeroInt], which may involve rounding or truncation,
 * or returns an encapsulated [IllegalArgumentException] if this number equals zero.
 */
fun Number.toNonZeroInt(): Result<NonZeroInt> = runCatching {
    require(toInt() != 0) { "Number shouldn't be 0." }
    TODO("Build a NonZeroInt instance.")
}

So, we should make this validation as early as possible, so users don't need to dive into complex stack traces.

[LVMVRQUXL]

This is only applicable if we still use exceptions in Kotools Types 5.
We are still thinking about it, but we may switch to customized Error types like InvalidArgumentError instead of exceptions for the following reasons:

• we often only need the error message
• computing the stack trace is a heavy operation.

These customized Error types will include a toThrowable or toException function for converting the error to the appropriate exception.
For doing so, we will use the Result type of the kotlin-result library instead of the one from the standard library.

[LVMVRQUXL]

Avoiding variable number of arguments

Source: Predictability chapter in Kotlin guidelines.

Using variable number of arguments copies arrays under the hood.
Because this operation costs a lot, we should avoid using it.

For instance:

• in Kotools Types 4, the NotEmptyList type can be created with the notEmptyListOf and the Collection.toNotEmptyList functions.
• in Kotools Types 5, users should create a NotEmptyList with the Collection.toNotEmptyList function only because the notEmptyListOf function use variable number of arguments.

[LVMVRQUXL]

Avoid data classes in public API

Source: Backward compatibility in Kotlin guidelines.

In Kotools Types 4, some types are defined as data classes (NotEmptyList for example).
This makes the API incompatible with its previous versions (see examples in the Kotlin guidelines).

Instead, we should define the API with classes or sealed interfaces for enabling backward compatibility.

[LVMVRQUXL]

Avoiding infix keyword on operator function

Any function declared as an operator should use the defined operation. This makes the code more readable and easier to understand.
Because the infix keyword sometimes makes impossible the conversion to the defined operation in IntellIJ, we should not declare an operator function in conjunction with the infix keyword.
Here's an example:

infix operator fun NotBlankString.plus(other: String): NotBlankString // bad
operator fun NotBlankString.plus(other: String): NotBlankString // good