DEV Community: Amol

Clear and honest code

Amol — Fri, 11 Aug 2023 18:30:00 +0000

When working with a huge code base, it's common to forget how a specific code block (function, method, or class) is implemented. However, the IDE suggests using a signature. Sometimes calling a code block can come with unpleasant shocks. By creating honest and clear code blocks, this can be prevented.

For example:

// (account: Account, amount : BigDecimal) -> Account
fun credit(account: Account, amount : BigDecimal): Account {
  if(amount < ZERO) throw NegativeAmountError(amount)
  return account.copy(balance = account.balance + amount)
}

By looking at the signature, caller simply does't know that it's going to blow up. This kind of code blocks affect engineer in 2 ways

Increase cognitive overload of reading and understanding each branch of the code block before calling it
hampers trust of code block.

Honest signature could have been something like

(account: Account, amount : NonNegativeCurrency) -> Account
// or
(account: Account, amount : BigDecimal) -> Either<NegativeAmountError, Account>

These 2 signatures appear quite straightforward, yet they use 2 different techniques.

The first signature prevents entry into an incorrect state by forbidding negative input.
While allowing erroneous input, the second signature communicates output more precisely. It informs the caller that it may provide an error or credit to their account.

References

Treat Type as set Read here and here
Algebraic data type

Code that changes together, stays together

Amol — Mon, 01 Aug 2022 18:30:00 +0000

In traditional clean/layered/onion architecture code is organized in layers and so as the abstractions such as controllers, services, repositories.

What I have seen most of people do is tried to organize code per layer by structuring code around those layer.
For example

- src
 - controllers
 - services
 - use case
 - entities
 - repositories

In some projects, where I see team wanted to build modular monolith, they started to group based on some heuristic, that these pieces goes together probably we should modularize it.

- src
 - module#1
  - controllers
  - services
  - use case
  - entities
  - repositories
 - module#2
  - controllers
  - services
  - use case
  - entities
  - repositories

I consider this way of modularizing code base as premature as it suffers from forcing you to make decision when you the least knowledge about the system. Sometimes this kind of modularizing felt so artificial.

So I was wondering 🤔

how we could defer decision of making modularizing code structure as much as I can?
How can I let code structure evolve itself organically?

There was another problem, If I want to make any changes, I have to make changes in upon 4-5 different packages such as controller, services, use case. In lot of cases I felt that it's lot of ceremony and dancing around so many files. There was urge of keeping things together.

Suddenly something clicked

"Neurons that fire together wire together" or "Family thats eats together, stays together"

which leads to

**Code* thats changes together, stays together*

As I move code which was changing together closer, 2 things happened

Code thats was coming closer, coupling between them increased(on vertical access).
Coupling between different slices started to drop

After spending more time with this approach, I learned that code thats shared across slices bubbled up and moved into core of the feature or is a domain concept. or it's just cross cutting concern. which then could moved up and finds it own place not just in code base but also conceptually.

In summary this approach provide me following flexibilities

✅ Code structure can evolve as organically as with our understanding of the domain concepts.
✅ Provide a way be more pragmatic per slice.
✅ Provide way of grouping which can scale with growing feature sets.

Final code structure was similar to 👇🏼

- src
 - todo
  - api
   - dto
   - controller
  - find-todos
  - complete-todo
  - new-todo
  - todo
 - notes
  - api
   - dto
   - controller
  - new-notes
  - recent-notes
  - note

Nature, Impact and Value of Change

Amol — Tue, 15 Feb 2022 10:00:00 +0000

In this article, I'm sharing lesson and learning about change. How understanding nature, impact and value of change resulted into more clarity and confidence and helped me to prepare release plan.

Situation 🤺

Like my other colleagues, I also have been part of such Task force couple of times. But recently in my task force, it was becoming very hard to come up with proper release plan. We're struggling to make a release plan which can be delivered incrementally and iteratively.

Background 📜

What is task force ? 🤔

At layer we form a triplet of Tech, Product and Business in order to refine features. Mostly one person from each area. Sometimes Product owner represents expertise in business or act as proxy for business. For each epic people rotates from each area. This helps to create opportunities to learn, grow and avoid biases in the company. We called such triplet as Task force.

Task force has following responsibility 💪

Refine feature aka epic
Be a point of contact for all the QA during crunch time.
Prepare release plan

Still picture was not very clear in 🧠

We had few brainstorming meetings but still picture was not very clear in our head; so I decided to analyse this epic critically and come up some options.

What we did 🤞

I decided to start from clean slate and look at this feature from users point of view. To do that I asked following question for each concepts and change that we wanted to bring in.

What problem it solves for user?
What problem it might create for user?
What is the nature of this changes?
- Breaking change - if it breaks or changes existing concept/feature drastically and changes affects user flow.
- New change - there was no such concepts exist before into the system and it may or may not affect user flow.
- Enhancement - changes refines existing concepts but not so drastically and may not affect user flow.

After doing this analysis and spending few hours, I realised more than 70 % changes were either enhancement and new changes and ~ 30 % were breaking changes. Just doing analysis unblocked very big chunk of feature and it bring ton of clarity in my head.

For breaking changes, I did one extra step I asked same 3 questions for existing feature to gain more clarity. After that, I knew exactly what we're taking out and giving back to the user. Now it was very easy to spot and fill the gaps.

In summary

I learned that understanding nature, impact and value it brings to the user are very crucial aspects.

Picture credits goes to Aziz Acharki
NOTE: If you have similar learning, please share your experience with me. There is always something new about every experience.

Fine control over execution in kotlin

Amol — Tue, 12 Oct 2021 10:00:00 +0000

Programing language that supports concurrency and parallelism needs to provide cancellation mechanism as well. Well thought cancellation mechanism also gives space to clean up resources.

In this blog post we’ll take see how to cancel coroutine and impact of suspend functions on it.

Basics

The Job interface has a method called cancel, which allows to cancel the job.

fun main() = runBlocking {
  val job = launch {
    repeat(1_00) { i ->
      delay(200)
      println("printing $i")
    }
  }

  delay(1_150)
  job.cancelAndJoin()
  println("cancelled successfully")
}
// printing 0
// printing 1
// printing 2
// printing 3
// printing 4
// cancelled successfully

Calling cancel has following effects on job.

ends execution job at first suspension point
if job has some children, they are also canceled at first suspension point
Once job is canceled, it can not used as a parent for any new coroutines.

Lets verify our first assumption by replacing delay call by Thread.sleep

fun main() = runBlocking {
  val job = launch {
    repeat(1_00) { i ->
      // delay(200)
      Thread.sleep(200)
      println("printing $i")
    }
  }

  delay(1_150)
  job.cancelAndJoin()
  println("cancelled successfully")
}
// what will be the outcome?

// outcome:
// printing 0
// printing ..
// printing 99
// cancelled successfully

Thread blocking code

Once we removed delay function job has no suspension point and hence it continues to work until the end of computation. Thread.sleep is thread blocking function let’s extract repeat code block into suspended function.

fun main() = runBlocking {
    val job = launch {
        repeat(1_00) { i -> threadBlockingFn(i) }
        println("job completed")
    }
    delay(1_150)
    job.cancelAndJoin()
    println("cancelled successfully")
}

suspend fun threadBlockingFn(i: Int) = coroutineScope {
    Thread.sleep(200)
    println("printing $i")
}

fun println(msg: Any) = with(Thread.currentThread()) {
    kotlin.io.println("$id:$name\t=> $msg")
} 
// what will be the outcome?

// outcome:
// 1:main   => printing 0
// 1:main   => printing .. 🧐
// 1:main   => printing 99 🤔
// 1:main   => job completed
// 1:main   => cancelled successfully

job is running on single thread and even we have suspended function threadBlockingFn main thread does not get unblocked to observe cancellation request. So how to create suspension point in this case?

In order to have more fine control, lets create coroutine for every call of threadBlockFn and join it back with parent job

fun main() = runBlocking {
    val job = launch {
        repeat(1_00) { i -> launch { threadBlockingFn(i) }.join() }
        // also produces same output
        // repeat(1_00) { i -> async { threadBlockingFn(i) }.await() }
        println("job completed")
    }
    delay(1_150)
    job.cancelAndJoin()
    println("cancelled successfully")
}
// output: 
// 1:main   => printing 0
// 1:main   => printing 1
// 1:main   => printing 2
// 1:main   => printing 3
// 1:main   => printing 4
// 1:main   => printing 5
// 1:main   => cancelled successfully

Lets use default dispatcher to delegate threadBlockFn execution

fun main() = runBlocking {
    val job = launch {
        repeat(1_00) { i -> withContext(Dispatchers.Default) { threadBlockingFn(i) } }
        println("job completed")
    }
    delay(1_150)
    job.cancelAndJoin()
    println("cancelled successfully")
}
// output: 
// 14:DefaultDispatcher-worker-1    => printing 0
// 14:DefaultDispatcher-worker-1    => printing 1
// 14:DefaultDispatcher-worker-1    => printing 2
// 14:DefaultDispatcher-worker-1    => printing 3
// 14:DefaultDispatcher-worker-1    => printing 4
// 14:DefaultDispatcher-worker-1    => printing 5
// 1:main   => cancelled successfully

Summary

Coroutine, dispatcher along with suspended function provides very powerful mechanism to have full control over execution of code blocks. Default function such as delay are cancel aware functions. To summarize, I would say use following thumb rules to achieve fine controlled code

Have more suspension points in code base
Avoid thread blocking code areas
coroutines are very lightweight, use them more frequently
use async/await, withContext around appropriate spaces
Break down computation heavy operation into smaller pieces with more suspension points

Dispatchers

Coroutine has different kind of dispatchers available as mentioned in the doc

Dispatchers.Default — is used by all standard builders if no dispatcher or any other ContinuationInterceptor is specified in their context. It uses a common pool of shared background threads. This is an appropriate choice for compute-intensive coroutines that consume CPU resources.

Dispatchers.IO — uses a shared pool of on-demand created threads and is designed for offloading of IO-intensive blocking operations (like file I/O and blocking socket I/O).

Dispatchers.Unconfined — starts coroutine execution in the current call-frame until the first suspension, whereupon the coroutine builder function returns. The coroutine will later resume in whatever thread used by the corresponding suspending function, without confining it to any specific thread or pool. The Unconfined dispatcher should not normally be used in code.

Private thread pools can be created with newSingleThreadContext and newFixedThreadPoolContext.

An arbitrary Executor can be converted to a dispatcher with the asCoroutineDispatcher extension function.

Modelling value types in kotlin

Amol — Wed, 04 Nov 2020 00:00:00 +0000

In this article, you’ll see how to model value object¹ particularly in kotlin.

Imagine we want to improve below model:

class Customer(id: UUID, email: String,..)

class Order(id: UUID,..)

I had 2 use reason for modelling value type

Type safety

lots of time I want to distinguish between let’s say customerId and orderId. so that accidental passing of wrong Id can be avoided. the best way is use inline class² concept but be careful with it’s stability status.

// option #1
inline class CustomerId(val value: UUID)
// option #2
data class CustomerId(val value: UUID)
// option #3
data class CustomerId(private val value: UUID) {
    override fun toString(): String = value.toString()
    fun asString(): String = value.toString()
    fun asUUID(): UUID = value
}

Option 1 and 2 are more recommended where as option #3 is example of over modelling.

I often have tendency to make props as private by default. but when we’re modelling immutable data type. You don’t need to mark props as private.

Represent a domain concept with constraint

Let's take an example of email which need to match some fancy regex.

This is bit complicated one especially with kotlin because of language design. But we have 2 options here:

Use constructor to throw violations 😟
```
data class Email(val value: String) {
    init {
        // if (!isValid(value)) then throw InvalidEmail()
    }
}
```
This option is not bad but it has few limitations and such as
- constructor is not honest enough because it can blew on your face
- it can hijack your program’s execution
don't use kotlin since well-known design flaw ³ 😅
Use NoCopy plugin 🎯
There is really nice article about NoCopy here.

Summary

Kotlin has few limitations but those can be fixed. Always go for more transparent and honest representation.

https://martinfowler.com/bliki/ValueObject.html "Value object" ↩
https://kotlinlang.org/docs/reference/evolution/components-stability.html#current-stability-of-kotlin-components "inline class is at Alpha stability level" ↩
https://youtrack.jetbrains.com/issue/KT-11914 "Confusing data class copy with private constructor" ↩

Introduction to Http4k

Amol — Mon, 27 Jan 2020 00:00:00 +0000

Couple of weeks ago, I was looking for very simple way to create web server. I found http4k which is a lightweight but fully-featured HTTP toolkit written in pure Kotlin that enables the serving and consuming of HTTP services in a functional and consistent way.

Some of Features of http4k

small, written in functional kotlin with zero dependencies.
very simple, no magic, no reflections.
immutable http model, which make it very easy to test/debug.
serverless / server independent

WebServer as Function

http4k is designed as application as function. Web server can be looked as one big function which handles requests.so it’s literally represented as typealias

typealias HttpHandler = (HttpRequest) -> HttpResponse

An endpoint which echos request body can be created just by 2 simple lines.

val app: HttpHandler = { 
    request: Request -> Response(OK).body(request.body) 
}
val server = app.asServer(SunHttp(8000)).start()

Request and Response are immutable objects. SunHttp is container which only meant for development. For production use Netty, Jetty, ApacheServer etc.Because app is just kotlin function, it can be composed very easily.

Filters

http4k provides a Filter function which is basically intercept the Request/Response pipeline and

typealias Filter = (HttpHandler) -> HttpHandler

Below code snippet shows typical composition of HttpHandlers.

val setContentType = Filter { nextHandler -> 
        { request -> nextHandler(request)
            .header("Content-Type", "text/plain")
        }
    }

val composedApp = setContentType.then(app)

Routing and composition

http4k provides some high level functions which helps to compose application which handles each request differently depending upon url, method etc. These functions accepts multiple httpHandlers and return one handler which is composed of them.

val app : HttpHandler = routes(
    "/api" bind GET to apiApp
    "/other" bind routes(
        "/get" bind GET to {_:Request -> Response(OK)}
        "/post" bind POST to otherPostHandlerFn
    )
)

Conclusion

http4k really stands with the promises they made. API from http4 are written very thoughtfully and are not opinionated. They are easy to reason and work with. Only downside can be no support for coroutine.

To know more about http4k rationale visit http4k/rationale

PS: This is my very first post. For correction please raise pull request at gitlab.