5 ways we keep our code understandable for junior engineers

1. Code structure

It’s arguably the hardest part of starting a new dev role - being presented with a repository, (or several), and having to figure out how everything works and fits together. At Learning Pool, we aim to structure files and folders in terms of entry points such that we match the structure of the app from a user’s perspective. We find this helps with navigating the code more easily, especially for junior engineers.

This also ties into trying to keep files and functions to a reasonable size, using our linter’s (ESLint) guidelines - ​​below 100 lines of code for files and below 20-30 lines for functions. To do this, we try to limit a file to a single function and make the name of the file match the name of the exported function. This makes it as clear as possible to anyone who is looking for a piece of code they haven’t seen before.

2. Naming conventions

This is an obvious one. If you name a variable or function accurately, clearly and concisely, then when someone new sees it, they know what it’s supposed to do without having to pick through lines of code to figure it out. Improves readability and saves time - no brainer.

Each language is different when it comes to how something should be named. In JavaScript (and TypeScript), we prefer to use UpperCamelCase for the names of all types such as classes, interfaces, types, enums, etc, and camelCase for variable and function names. We don’t try to differentiate the case between variables and functions because functions are data and can therefore be stored in variables. For function names, we expect a verb followed by a noun. For boolean variables, we usually prefix with is or has, (when it makes grammatical sense!).

3. Built-in language standards vs. Lodash

JavaScript is pretty powerful. It has a lot of built in language standards that have improved over the past few years. Before JavaScript had features like the spread syntax and the Array.prototype.map function, libraries such as Lodash were necessary, but now we have a choice.

We prefer to use built-in language standards over libraries in our code for a few reasons:

• It reduces the amount of code required to be interpreted and in some cases bundled therefore reducing our load and run times
• Junior engineers are more likely to be taught the built-in language features over libraries, so why make it unnecessarily complicated.
• Standards are generally better supported than libraries in terms of fixes and security patches. If the built-in standards just don’t cut it, we try to only use one library (in our case lodash) so that juniors don’t have an endless list of things to learn.

4. Pure stateless functions over impure stateful classes (Functions vs Classes)

It’s easy to get caught up in discussing different design patterns and where code ‘belongs’, and there isn’t always a right answer. On Learning Locker, we use React and Redux on our front-end and have done for a few years before Hooks were introduced in React 16.8.

A lot of our code was originally written in classes, but we’ve been moving towards using pure stateless functions over impure stateful classes where possible (and where appropriate).

There are already quite a few places where you can read the pros and cons in detail. We try to avoid endless refactoring, so this is a slow process, and generally follow the ‘Boy Scout Rule’ here.

“Leave this world a little better than you found it.”
— Robert Baden-Powell (founder of the world Scouting movement)

5. Code reviews

It’s common knowledge that the best way of learning is by doing. We include juniors on our code review rota, and pair them with another engineer so that they can explore further parts of the codebase. If a junior doesn’t understand a piece of code that a fellow engineer has written, maybe there’s a good reason. And if not, then at least they’ve learnt something more complex in the process. For an engineer to explain their code to a junior can also lead to rubber ducking moments where a lightbulb moment happens and a bug is discovered.

Join us

We’re often hiring - you can find all our job listings on our website.