July 2022

As software developers, we’ve all been there: you’re writing some code, you know it’s dirty, but the deadline‘s coming closer, and you go: "it’s working now, I’ll just refactor it later", and we all know how that turns out.

This repeats a few times, and before you know it, it’s just one big bowl of spaghetti that you don’t want to touch anymore.

Let’s look at a few things you can do to help the next developer who looks at your code. After all, that developer could be future you!

We’ll look at a solution for the first puzzle of Advent of Code 2021. The puzzle has 2 parts, our solution includes part 2.

The assignment goes like this:

• You get a list of integers
• Use a sliding window to go over them
• Calculate the sum of each sliding window
• Count the number of times the sum of each window increases

This code solves the puzzle:

When you glance at the code, you can kind of get an idea of what’s happening, but you have to read the whole thing carefully to understand or make a change. It’s not clean code.

It’s not necessarily a problem to have this kind of code when you’re exploring a solution, as long as everything fits in your head. But it’s not the kind of code that should end up in production. As software developers, we read code much more than we write it. So if we want to be efficient as developers, we should prioritize writing code that is easy to read and understand, not quick to write.

The first advice you typically get is:

• Use clear names
• Document unclear code with comments

So let’s do that.

This is exactly the same code, but with better names and some clarifying comments:

That looks better already, doesn’t it? It’s clear that there’s something going in with sliding windows, making sums and counting increases.

Now comments are all well and good, but as Robert C. Martin points out in Clean Code, they have a tendency to get out of date. Let’s assume for a minute that the requirements change (don’t they always?): instead of the sum, we should use the median to detect increases. In this kind of scenario it often happens that someone updates the code but doesn’t update the comments. Now the comments say "sum" but the code says "median" and it’s just confusing instead of clarifying. We might spot that quickly in our small example here, but when you’re working on a large project it can get really crazy when you’ve been staring at the same code for hours, and you suddenly realize that that comment you trusted was lying to you all along!

That’s why it is better if you can explain yourself in code.

Let’s see what that looks like:

That’s quite clear, isn’t it? Without any comments!

By extracting functions and giving them meaningful names we can clearly communicate what’s happening without using comments. We can explain ourselves in code. It’s clear from the code that we’re using sliding windows and that we’re counting increases based on the sum of these windows.

Could we improve it even more?

Let’s compare the code to the description of the solution in plain English:

• Use a sliding window to go over them
• Calculate the sum of each sliding window
• Count the number of times the sum of each window increases

Is it clear from the code that this is happening? It’s certainly more clear than the first version, but everything is in 1 for loop and your fellow developers (and future you) would still need to read the code carefully to understand what’s happening.

Let’s see what happens if we decouple our solution into self-contained steps:

countDepthIncreases() is only 3 lines now. One for each step we described in English. It’s not necessary to go look at the implementation of the different functions to see what’s going on here. When a change is need, it’s quite clear where the change needs to happen and because the different steps are self-contained it is less likely that a change to one part will break another part of the solution.

Need to use median instead of sum to detect increases? ok, no problem, write a median() function and replace it:

Need to count decreases instead of increases? ok, no problem, write a countDecreases() function and replace it:

Apart from readability, there is an added benefit to these self-contained steps: you can mix-and-match to create different variations of the solution and reuse parts of it in something completely different:

• Need to count increases of both sum and median? Ok, you can add more 3-line functions for different variations
• Need to do something else with sliding windows? Ok, you can reuse calculateWindows()

In summary:

• Use clear and meaningful names
• Always try to explain yourself in code
• Use comments only when you can’t explain yourself in code
• Decouple your solution into self-contained steps that do 1 thing

So you would like to grow as a developer?
Great! There’s a lot of good information out there.

But there is so much! You can feel like there’s a massive mountain of things to learn, and you don’t know if you have time to even scratch the surface.
It’s overwhelming, you’re worried that you’re not meeting expectations, and you’re freaking out.

Don’t freak out, please don’t.
Instead, ask yourself this question:
Has anyone brought up your performance?
The answer is probably no.

That’s because this is normal. It’s impossible to know everything. No one knows everything, not even that mythical developer you run into on social media that seems to be an expert on every subject.

This is especially true as a full stack developer. It is often expected of you to handle a wide range of tasks. Being able to learn what you need for the task at hand is important. But technology changes so fast, especially if you’re dealing with frontend development.

So what do you do?

As a junior developer, learn about the frameworks and libraries you use at your job. It will boost your confidence and make you stand out. Avoid learning the "best" library for X or knowing all the frameworks. That’s just FOMO. The technologies you use do not make or break you as a developer.

When you start to get more experience, you will encounter different environments with different technologies. You could focus on learning all the inns & outs of those technologies every time, but how much will that effort pay off in the future? When you get a new position or change jobs, a lot of that time will be wasted.

If you want to grow without getting overwhelmed, here’s 2 things to focus on:

1. Learn the fundamentals of building good software. Things that won’t be obsolete in a few years and things that help you understand how technology works.

Having a solid grasp of the fundamentals enables you to be much more effective as a developer. You waste less time, learn to use new technologies faster and most importantly: you build better software both technically and functionally.

Good resources on fundamentals for full stack developers:

• Clean Code by Robert C. Martin (aka. Uncle Bob), about (you guessed it): writing clean code.
• Composing Software by Eric Elliott, about FP in Javascript. There is a disclaimer though.
• Head First Design Patterns by Eric Freeman and Elisabeth Robson, about OO and design patterns.
• Designing with the Mind in Mind by Jeff Johnson, about fundamental UI design guidelines.

Tip: avoid the trap of thinking that you have to read every chapter in a book to be able to "check it off" or to "say that you read it". If you read one chapter, and you are able to apply it and get value from it, that’s great!

2. Have a high-level idea of the technologies that are relevant to you, without going deep.

You can learn about new technologies, but you only need a high-level idea of what they’re about.

Ask questions like:

• What problem does this technology solve, what’s a realistic use case scenario?
• What are the ups and downs?
• Why are people excited about it?

If you do this, you will have a mental toolbox of technologies without spending an excessive amount of time learning them. When you need to solve a problem that a technology addresses, that is the time to learn more about it. It’s part of your job, so it’s ok to do it on the job.

No one can expect you to know everything.