The code you write should follow a similar level of detail.
I mentioned level of detail in an earlier episode about how to start building a video game. And there I was talking about how to get your game idea or any project idea to a level of detail where you can begin working. This episode is more of a follow up to last week’s episode where I explained how to watch out for differences.
Listen to the full episode or read the full transcript below for more examples and how to fix your code so that it’s more readable and understandable.
Transcript
I mentioned level of detail in an earlier episode about how to start building a video game. And there I was talking about how to get your game idea or any project idea to a level of detail where you can begin working.
This episode is more of a follow up to last week’s episode where I explained how to watch out for differences.
Before we get too far though, I wanted to clarify the example that I used last week. I mentioned a bat. And in my mind, I was picturing the flying mammal type of bat that comes out when the sun sets to eat mosquitos and moths. But I also mentioned a baseball. Putting the two together might lead you to think of a baseball bat instead of the cute furry animal with pointy ears.
If anything, this shows what I was talking about in episode 2 about why we need programming languages at all. Any natural spoken language is full of misunderstandings like this.
I’d also like to mention that this podcast explains real programming topics and each episode is dedicated to a single topic. As much as possible anyway. That means that any episode from episode zero up to whatever is the current episode are all relevant. You can listen to any episode to gain insight and improve your skills in programming.
If you listen to the earlier episodes, they all had sponsor advertising. But I never found a good sponsor that you would benefit from so I decided to sponsor the show myself. I still get offers to advertise on the show and turn them down usually because the product is not related to programming.
Most of the early episodes promote live classes. Right now, the best way for you to participate in live classes with me is to become a sponsor of the podcast and select a reward level that includes live programming sessions. This is where you can participate as we build a game. You get to see how to approach problems and how to write code that does what you want.
Just visit takeupcode.com and click on the link at the top to become a patron.
Today, I’m explaining how to watch out for differences in the level of detail in your code itself. All this talk of earlier episodes reminds me that I haven’t used cooking in my examples in a while.
Imagine that you’re following a recipe to bake bread. And it explains how to mix the ingredients into a bowl. But when the recipe gets to the flour, instead of telling you to add 2 cups of all purpose flour, the recipe gives you the steps needed to harvest the wheat and the steps needed to grind it into flour.
Now these steps are definitely needed. But not when trying to bake bread. All the basic ingredients have to each go through their own production steps. And it makes a recipe completely unusable when it mixes levels of detail like this. In fact, the example I gave you is so ridiculous, that nobody would ever consider writing a recipe like this.
But why then do we write code like this? I see it all the time. Even in my own code. Yes, I have to be careful about this too. We all do.
I’ll be writing a method with lots of detailed instructions and right in the middle will be a call to another method that wraps up other instructions.
Don’t get me wrong. I’m not suggesting that you avoid putting code into methods. All I’m saying is that the code becomes more readable and more understandable when it’s all at a similar level of detail.
So instead of writing ten lines of detailed code followed by a call to a method that wraps up another ten lines of code followed by another ten lines of detailed code, try wrapping up the first and last ten lines in their own methods. Now your method consists of three calls to methods that are each roughly the same level of detail.
Since each method has a name. You are giving your methods meaningful names, right? Okay, since each method has a name, it’s easy to understand what the series of three calls will do. A lot better than trying to read through twenty or so lines of code and missing the one call in the middle that does a bunch of work itself.
The point is when writing code, that you should consider making a method to encapsulate other code anytime you find yourself writing code that mixes detailed code with calls to other methods that have their own detailed code inside.
You might hear some advice that says you should turn your code into a method anytime you want to reuse it in different places in your code. That’s true. But even if there’s just a single place where your code is needed, you can still benefit from turning it into a method if it needs to be called along with other methods.
It will help make your code read better and keep each method focused on a single task with instructions inside that are all similar.
Hey, that’s actually a lot like how I try to structure the podcast episodes. This advice applies to many things we do in real life. Watch out for differences and you’ll write better code.