When you study computer science, or first get into toying around with it in your spare time, you find yourself working on a lot of small projects, just to get your feet wet. ‘Hello World’, a program which simply prints the text ‘Hello World!’ is perhaps the most-written program of all time. As your projects get bigger, the code behind them gets more complex, and you, as the software architect, have to keep track of everything that’s going on. This seems like a pretty easy task when working on a guess-the-secret-number game. But what happens when your codebase becomes BIGGER THAN YOUR ENTIRE BRAIN?!
Untangling The Web
In case you couldn’t tell from all the words about code, computer science, and programming, this post is gonna be one for the more technical folks out there. However, that doesn’t mean that there aren’t lessons to be learned by anyone else – keeping track of complex systems is a skill that applies to any project management task!
Real-world systems are incredibly complex – even more so than they appear, even after working with them for a while. As you add features, fix bugs, and increase the overall complexity of your code, you suddenly find yourself stuck in a tangled web of your own design. Now, the best way to combat this is simply to write good, clean code and follow good design patterns. However, if you want some advice other than “just do everything exactly right”, then read on!
Where Shadows Slumber isn’t the most complex game, but the implementation behind it is very intricate, and I definitely didn’t do everything exactly right. As the only developer on the project, I have to keep track of everything, which is a lot of stuff. Here are some tips I’ve developed for not going crazy trying to understand a system that you yourself created!
Tip 1: Divide and Conquer
The first application of divide and conquer is exactly what it sounds like – take the whole system, divide it up, and give a different part of it to each team member. While this doesn’t really apply to the development of Where Shadows Slumber, it’s still worth mentioning. If you’re in charge of one part of your project, and someone else is in charge of another part, there’s less minutiae for you each to keep track of. You only have to know how the pathfinding (for example) works on a higher level – the intricate details of the exact implementation are left for the ‘pathfinding team’. And if you do need to understand how pathfinding works, there’s someone who knows all about it – and that’s what teammates are for!
The other application of dividing and conquering is what I’ve heard referred to as ‘the Google Maps approach’. When you’re looking at a map of the world, you don’t need to be able to see every single city. But if you’re looking at a map of a state, you probably do want to see them all. So, the amount of detail you get depends on the context in which you’re examining it.
How can we apply this to project management? It’s really just a state of mind. When you’re thinking about your whole project, try to think of it from a more abstract point of view, rather than considering all of the details of the implementation. This kind of thinking happens naturally, but we want to actively embrace it. You want to think of the smaller parts of your project as a ‘black boxes’ – you give them some input, and they give you some output. You don’t know (or care) how it gets figured out, until you need to look at that code – at which point, you shouldn’t be thinking about the rest of the project. By only caring about the part of the project you’re currently working on, you free up a lot of space in your head.
Tip 2: Keep It Simple
The best way to prevent your project from becoming too complex is, obviously, to keep it simple!
This comic is a comic [Image credit: xkcd.com]
do you keep your project simple?” I can hear you asking. The key is in how you think about your code. For the most part – and there are notable exceptions – you should be able to think about or describe the function of different parts of your code with ease. Doing so might require the context within which that piece is working, but given that, it should be relatively simple.
Now, don’t get me wrong – your code itself will probably be very complex. However, it’s important that any code has a specific purpose. If some piece of code doesn’t have an easy-to-determine purpose, consider why it’s there and what it’s doing. If possible, see if you can move parts of it into the appropriate parts of your project.
Additionally, when describing the purpose of a section of your code, make sure it’s a relatively simple purpose – the best way to do this is to avoid the word “and”. If the purpose of a file is “to perform pathfinding and determine nearby enemies”, it would probably be best to split that into two different files.
By keeping your code as simple as possible, at least from an organizational perspective, you won’t have to strain yourself every time you try to remember what your code is trying to do.
Tip 3: Organization
Speaking of organization, keeping your project organized is one of the best ways to keep it under control. This can be tricky and surprisingly time-consuming, which is why people so often shy away from it, but it can also be crucial to your success. The key here is to create sensible patterns, and then follow them.
Everything is right where it should be!
The easiest way to apply this is in directory structure. Make a decision toward the start of your project how you’re going to organize everything, and then stick to it. For Where Shadows Slumber, as you can see, we sort most things by world. All of the levels, materials, and textures for World 1 are in the same folder, since they all apply to the same levels.
However, notice that there are some folders which are not organized by world. Scripts and prefabs are examples of things which span across worlds. While a model or texture might be specific to a certain world, the shadowCharacter.cs script, or the pathfinding node prefab are not, so why should they be sorted by world?
Thinking through your project and deciding on a directory structure that makes sense can make it a lot easier to understand what’s happening in your project. And, every so often, you should re-examine your organization, make sure it still makes sense, and make sure you’re actually following it. In this way, you can be organized, stay organized, and know that your organization is actually effective.
There are also organizational paradigms that you can apply to your code to keep it clean. One of my favorites is the idea of data ownership. The idea is that every piece of data in your project (the location of the character, a bullet’s speed, the number of points a player has, etc.) should have an owner. It’s usually pretty easy to figure out who the owner should be, but sometimes it can be tricky – and it’s in those cases where it’s important to know. If my shadowCharacter.cs script is the owner of the character’s position and velocity, then no other code should be allowed to mess with those values. That way, if there’s a problem with the character’s position, you know exactly where to look.
This is just one example of an organizational coding pattern, but the concept behind them all is pretty similar – at every point, you want to make it easier to understand what your code is doing. It’s a whole lot easier to make changes, fix bugs, and implement new features when the things that your code is doing actually make sense to you.
Tip 4: Not Too Complex… Yet
Every project starts out small and simple, and yet we constantly find that our projects have gotten out of hand, growing into sentient monsters, taking over our lives and ruining any chance we had of success – who knew that project management was so much like parenthood?
Incredibly clever comments aside, if our project starts out simple and ends up complex, there has to be some point when it started to go awry, right? And if so, there’s probably a point when we could have noticed it going wrong and steered it back on track. Thus, it’s important, as you’re working, to be constantly considering the state that your codebase is in. Every so often, ask yourself; is this code still clean? The more often you ask yourself this question, the sooner you’ll know when you start heading in the wrong direction – it’s much easier to fix this problem if it’s only just started to go wrong!
This is the concept of technical debt – every so often, you add in some bad code, just so that you can meet a deadline, or get some functionality off the ground. Every time you do that, you’re increasing your technical debt – and if you don’t pay that debt, it adds up until your code is unmanageable. It’s always good to keep your technical debt in the back of your mind, and address it as often as possible.
In my experience, there’s one really good way to determine if your technical debt is getting to the point where it’s impairing your development. If you ever find yourself writing overly complex code, it probably means that you have an overly complex system.
Again, I’m not advocating against complex code in general, as it has its place. But if you find yourself writing complex code to do something simple, or repeatedly thinking “it should be easier to do this”, that’s a big red flag. If you ever fix a bug by ‘trying something’, but you don’t know exactly why it fixed the problem, that’s a sign that you don’t fully understand your code, and code that has exceeded your grasp is exactly what leads to very subtle (read: hard to fix) bugs.
When you get to this point, you should take a step back (and maybe a break), get a fresh look at your code, and spend some time cleaning it up. No one likes spending time on housekeeping tasks, but trust me, it’s a lot more fun spending an hour here and there cleaning up your code than it is mucking through an overgrown garden of technical debt.
This is by no means a definitive list, nor will every part of it apply to you or your project. Rather, these are just some of the philosophies I try to keep in mind as I’m coding and software architect-ing. There are plenty of others, but hopefully adding these to your repertoire will help you reign in your projects and keep them from becoming too complex!
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
If you have questions about managing complex systems, or want to share your own tips, feel free to contact us! You can always find out more about our game at WhereShadowsSlumber.com, find us on Twitter (@GameRevenant), Facebook, itch.io, or Twitch, and feel free to email us directly with any questions or feedback at contact@GameRevenant.com.
Jack Kelly is the head developer and designer for Where Shadows Slumber.