Ruby Kaigi 2018: Avoiding Cognitive Overload

I’d like to share a great talk by Julian Nadeau, a Production Engineer from Shopify. The title is Avoiding Cognitive Overload: Test for Productivity and Education. This is the link to his original presentation

Why?

There were a lot of great talks by great speakers in Ruby Kaigi 2018. In my opinion, Julian’s was one of the best talk. Because it was easy to understand, simple, and left a deep impression to me. This talk brought back my memories when I joined Bukalapak for the first time. It reminded me how I struggled with onboarding moments.

What?

It started from mistakes. People make mistakes. No matter who it is, inexperienced or even the most experienced developers make mistakes. Mistakes are bad. We want to avoid mistakes as much as possible.

We need some way to avoid mistakes. Some companies has rules or guidelines to follow to avoid mistakes. As a new employee, onboarding times is one of the most difficult things (at least for me, how about you?). I didn’t want to break things on my first day. Okay, so what should I read to avoid mistakes? Of course we have documentation for engineer’s onboarding.

Well, it was very helpful. It gave a lot of informations, such as: architecture of Bukalapak, how to setup the codebase, several important checklists, etc. For me, first pull request was daunting but thankfully it went smooth. Then bigger tasks were coming.

Files changed grew bigger, pull request’s reviews keep coming. I made mistakes. I should have read about that in “page A”. Ah, for the other mistakes I should have read it in “page B”. Ahh yes, I forgot about that one. Oh okay, my colleague told me about that a month ago …

That was what Julian called as Cognitive Overload:

Being given too much information all at once, resulting in being incapable of processing the information efficiently or at all.

These are some examples:

• Don’t add gem foo
• Don’t forget to add test files
• This class should only have one public method
• Use verb as class name
• etc

Those lists will grow bigger and bigger as your company grows. I’m not sure if you can remember those things unless you have a photographic memory.

How?

Okay, now we know what is the meaning of Cognitive Overload. Now, how do we avoid it?

Julian gave some solutions:

* Unit Test

Some of you might be familiar with unit test. It is used to test some logic in your code. So we assert an input to match expected output. How about using your codebase as the input?

For example:

• Rule: some class must use verb as class name.
  Solution: We can create a test to iterate the codebase, retrieve the file name, then match it with online dictionary.
• Rule: in Bukalapak’s code base, some class need to have type checking in the initialize method.
  Solution: For Ruby, we can create a test to read the file and parse it using Ruby’s Ripper API or using Parser to parse the file and check if the type checking is in place or not.
• Rule: this class should only have one public method
  Solution: well, the idea is similar as above.

* Style Guides

For Ruby, you can use Rubocop. It is a static code analyzer. Enough with debate of which style is better or easier to read, just use Rubocop and we can have consistent style guide in our codebase. Now, we can spend our time to review business logics rather than reviewing style guide.

* Just in Time Education

Means to provide education / information at the exact moment the user needs it, not before. It can reduce Cognitive Overload as you are given the information at the exact time. You don’t need to remember a bunch of stuffs at once.

* Other Solutions

Give a clear error messages so it is easier to understand. Some package managers give nasty errors which looks confusing and daunting. Julian wrote a bundler plugin to make gem installation more actionable, educative, and all around easier to understand. Check this out and contribute!

That’s all from me. Thanks for reading!