Scrolling through old Stellar Asylum code I saw common mistakes we’d been making over and over again. I didn’t know that when we were starting out with our project, but keeping codebase clean, readable and simple is essential to maintain having fun while programming. Due to lack of experience we kept making easy coding mistakes and over time developing new pieces became tedious and frustrating, every new feature was breaking existing features and it eventually killed off the joy we had from our work.



Fortunately, there are lessons to be learned from this. I present you a few tips to make your code more enjoyable, based on Stellar Asylum v1 mistakes!



1. Bad variable names

One of our critical scripts declares the following list of variables:

The wall of variables

As you may see this is incoherent, inconsistent wall of filth (including intentionally misspelling can’t with a ‘u’ instead of ‘a’). There are variables with abbreviated names, with joke names, with weird-telling-nothing-really names, even a one-letter names. Before we go any further let me say this: the more readable the code is, the better for you. Don’t mind the coworkers really, think about yourself. Your brain needs to struggle with all the complicated logic. Why making it harder due to obscurity? Describe the variable with an elegant name which capture its reason for existence. Doesn’t need to be the shortest, just let it descriptive. The clearer the name will be, the easier job you will have when working with it in the future. As a developer you will often read code, sometimes yours and sometimes not, but every time you will want to understand it. Help yourself, do not abbreviate anything. And God forbid one-letter names which are being taught at schools. This is the worst, it obscures everything. Give your future self a favor, and name your stuff appropriately. Based on their actual usage I renamed some of the worst-named variables from the list above:

So: Use descriptive variable names

2. Magic numbers



Very often you find yourself in need to use numeric value which stands for some constant, e.g. character jump force or width of a block in UI. You know what it is when you write it, but after some time you may not be that certain about the meaning of those numbers! For example, in SA we’ve ended up with code like this:

Wild 3.2 appeared!

Since every character in SA is running in circles we use in our code circular motion. Without getting into too much details, angle translates into position in our game. So adding a number to it, effectively teleports our Prisoner to another place. Since we kept it as 3.2, I couldn’t find out what position it is being moved to. After a few minutes I realized that this code moves a character a half of the circle (for sandbox tutorial purposes). Why don’t I extract this number to a constant and name it accordingly? Making it into:

Then, usage will look like:







Having extracted a number, lets me add a name, to be more clear about my intents. I just saved my future self a few minutes!

So: Extract raw numbers to constants

3. Huge chunks of code



Since we’re in the spirit of making code being read as a spoken language, let’s take this idea further and start extracting pieces of code to functions/methods. And again, you get to give a name to a piece of code! Now consider this:



Incomprehensible wall of code

If you’ve got no idea what’s going on it means you’re still sane and experience normal reactions. Code should not look like this. It ought to be descriptive. Now imagine, we’ve grouped these lines into three methods and assigned them a name:



Now focus on the calling site. Imagine you’re reading Update method for the first time and it looks like this:

Now this looks much better. It says everything about what it does. If you need to study the details of moving characters you jump into UpdatePosition and get the info you need. I’ve only extracted code to methods and everything became much more descriptive and less daunting.



4. Distinguishing the state



From structural view a game is a group of state machines. A state machine is an object which in any given point in time is in the one of the set of defined states. Consider a typical Prisoner from Stellar Asylum. It either runs, jumps or performs special ability. While designing an interaction for our character we’ve got to keep in mind that this interaction may happen in every state. For example when another Prisoner runs into (collides with) our guy it may happen when he’s running, jumping or performing special ability. That’s why what we should do was to assert all the possible states and group them into a finite set. In programming languages a perfect fit for this set would be an enum. if language of your game doesn’t have those, a set of numbers with assigned names will do. Having asserted all the possible states of the Prisoner, when designing, let’s say, collision, we may decide how our Prisoner should react depending on the state he collided.

We obviously didn’t do that. Instead, each time we wanted to add or tweak some behavior we added a boolean flag. Yes or no. The wall of possible outcomes grew exponentially with each new flag. Moreover we ended up with monstrosities like this:

To this day we’re not sure that we covered all the possible outcomes in this if statement. Having used enum with asserted states, our code which handles collision would look like this:



So: If you feel like adding a new if with a new boolean for some condition, stop and think. You probably should think of possible states your object may be in, and create an enum out of it.



5. Comments



Comments are plain text information, which is ignored while compiling/interpreting the code of your language. Their sole purpose is to add notes to your programs. And I proclaim them a pure evil, devil’s work and the root of all that’s bad in the world.



Now seriously. We’ve just finished the four tips that enhance readability of the code. Comments feel like its sole purpose is to do just that, help with readability. Instead, much more often, they add noise to your code. Using tips 1 – 4 should greatly increase the amount of spoken language in your code. Having self-descriptive programs eliminates the need for comments.



In Stellar Asylum you may find comments of all sorts. We wanted to keep an upbeat atmosphere and tended to fool around with names and comments. In the end, funny comments doesn’t help when you’re frustrated trying to find an error for three hours straight. Oh man, it just adds up to the anger. For example, to express self-doubt I added such comment:

It does not help. Self-doubt does not help with understanding, it only increases, well…, self-doubt? Why adding a code that may or may not work? It is littering your own garden. It feels like there should be saying like this, but I’m pretty sure it’s not that. 😛

Moreover keeping old code makes programs unimaginably harder to read. Nobody wants to remove code commented out. Maybe it will be useful? However, the reality shows that over time comments grow old, and quickly they put down roots. After a while no one dares to touch commented code and it remains a relict, polluting your scripts.

So: Let the codebase be as simple and clean as possible. Free of comments.



Summary



In general: name your shit properly. Give names to your operations, describe yourself via code, remove all the noise which is not necessary. These tips mostly come from Clean Code ideology from software development, if you feel like more of this check out the book and make sure not to miss out on the Part 2 with more advanced tips in the future!



Share your thoughts about tips in the comments! Next post arriving in two weeks! In the meantime play a match of Stellar Asylum with friends!

