Let me tell you a story about code clarity. If you’ve met me, I’ve probably told you this story before.

Back when I was in engineering school, I had some algorithmic courses. The teacher would often ask us how many lines a particular algorithm would take to solve. Some students would take guesses: - 10? - No. - 16? - No. - 13? - No. 3.

The first time we heard that answer, we thought we were in for some very clever solving that we haven’t heard about yet. And then the teacher would write down three function calls. Wait, that didn’t solve anything! They just tricked us. Those three lines don’t accomplish anything, we still need to write the bulk of the work in those functions. And in the end, we’re going to see fifteen to twenty lines so we weren’t far off.

The teacher asked us this question many more times. We were not expecting amazingly short algorithms anymore but we’d still think about solving the whole puzzle when guessing line numbers. And the teacher would never go above five lines for any algorithm.

At the time, we were mocking him. We couldn’t see the value of this way of thinking.

Fast forward now and it is one of the thing I do most when writing code. I’ll take a piece of paper and write the function names I’m going to implement. Or I’ll do it directly in my code editor, with real functions or comments. And I’ll also give that advice to any developer I meet.

It allows you to focus on one problem at a time. When you’re writing those function names, you are thinking about what the code should be doing. When you’re implementing the functions, you are thinking about how the code should do it. This clarity gives you the best chance to write code that is easy to understand for the next person reading it.

Team effort, cheap iteration

Your mind is focused on the problem to solve, on the different ways you could solve it. Once you’ve broken down the problem, you can discuss with your team which solution they’d like to implement. That iteration was pretty cheap because it didn’t take very long to imagine those different solutions. If you come with one solution fully implemented but the team would prefer another one, you might stick to your (less appreciated) implementation because it’s already done. Or the time you spent implementing is lost because now you have to start again.

Once the problem is broken down, you can even share the implementation work for a large task. Thanks to the plan you outlined, everyone is on the same page and will be alright working on their part.

Not sidetracked until needed

When you are thinking about the what, you don’t need to focus on the features of the language you are using. You’re barely using the language or maybe even using a pseudo-language. You’re less likely to get sidetracked looking up documentation or Stack Overflow, finding an arcane behaviour of the language, framework or library you’re using. You’re focused on the big picture.

When comes the time for the implementation, you can get stuck and confused. But that’s alright, that won’t distract you from the big picture, it has already been solved.

Good naming

As you create your plan to solve a problem, you’ll have to give names to the concepts you’re working with. Because you don’t have the full code to show your team, those names need to explain clearly what is happening if you want them to understand.

Those function or variable names can often replace the need for some comments¹. The team will think those names clearly express the intent because they’ve agreed to the plan. And when the code evolves, it is more likely for the names in the code to be updated. We’ve all seen comments being completely out-of-date with the code surrounding them.

Take the time to do it, it’s worth it

Something I thought was a joke as a student is now one of my favourite tools as a more experienced engineer. As a mentor to new developers on a team², I’ll often ask them to do that work and present it. That often leads to very interesting conversations on the architecture of the project, why we do things in a certain way. You can also easily discuss the benefits and drawbacks of each solution.