Make your code easy to run

Today, I want to write about steps you can take to make your take home test easy to run, and win brownie points with reviewers.

I spent a lot of time in the last half of 2023 reviewing take home test submissions. The company had opened hiring for junior through to senior positions, providing the same take home test for everyone. The goal of the test was to build a simple CLI application to search a provided JSON file containing a list of uniform entries. This is my favourite kind of coding test as it provides practical task simple enough to be completed in day, but with enough complexity to allow demonstrating one’s technical ability.

As both senior and junior applicants had the same test I got to see a full range of submissions from single file scripts to, dare I say, elegantly architected solutions. I think there was something to be learned from almost every submission, both from the approaches taken and the mistakes made. It’s even better when the submission meets the test’s functionality goals, has passing tests that cover the right things, and has coding of a good quality.

But even then, reviewing is a time consuming process that requires the reviewer to switch context from their current work. If you can help the reviewer make that context switch with as little pain as possible, you are already sending a clear message that you respect their time and care about their mental health. Possibly the best way to do that is removing as much friction as possible to get your code running correctly on their machine.

The following is written with reference to Ruby, but the basic principles probably hold true for any language or framework.

Specify the version of the language used.

At minimum this should be noted at the start of the README, otherwise in the Gemfile or language version manager dot file (.tool-versions, .rbenv, etc). While Ruby is generally backwards compatible, if the code is written with a modern version, there may be syntax that isn’t supported with the reviewer’s default version. While installing a new Ruby version may take time, it is better to do it up front than after having to debug issues when running the submission.

Specify dependencies using the appropriate package manager.

Using Bundler to generate a Gemfile for a project is straight forward and an industry standard at this point. In fact, for all the criticisms Ruby gets, its package management system is the one thing that most people agree it gets right. As above, it reduces dependency installation to a single command and saves the reviewer having to search the submission to make their own Gemfile themselves.

Detail how to get the code running

Provide a list of commands that the reviewer needs to run to get submission running. Assuming that they have nothing installed, following the commands exactly should get the language installed at the correct version along with dependencies. Also include the commands to run the test suite, as well as example commands for running the code. The goal is to allow the reviewer to evaluate the code’s behaviour without having to read any file beyond the README. Ideally it should be the same experience as installing well written project dependency or piece of software, easy to set up and getting running so you can focus on solving the problems at hand.

In summary

Aim to make you code as easy to run as possible so that the reviewer can focus on reviewing it rather than debug issues caused by mismatching versions and missing dependencies. This will reduce the cost of context switching, and allow they to focus their attention on evaluating the merit of your submission. It demonstrates an attention to detail and respect for your peer’s time that can help you stand out.

On the other hand, I have occasionally asked during interviews why there was no Gemfile included. Sometimes the answer is that they didn’t feel it was important in take home test, though they assured me, they would if it was a “real” project. I want to cover how I feel about that kind of response in a future post, but unless they are beginner who is really unaware of what is possible, it just strikes me as the bad kind of lazy.