Many folks diving into the brains of Spark are getting their first introduction to programming, because make no mistake; simplified though kode is, it is a programming language. Kode doesn't quite fit the mold of any other programming language I'm aware of, but there are still a lot of best practices for programming that apply. I'm going to go over just a few of the big ones that I think can help folks out when they start diving a bit deeper into the brains. I'll also mention some Spark specific recommendations that I came up with myself.
Before I go through the list, I'd like to briefly mention something. The recommendations here are all built around the understanding that with a little bit of extra effort up front, you can save yourself a lot of trouble in the long term. When I'm too lazy to take my own advice, I almost always regret it. With that, the list...
Variables are not just there in case a value needs to change during gameplay, they are a powerful tool for organizing and simplifying the maintenance of your kode. Let's say you want to create a UI, and you want to put a few squares next to each other on the screen, but you want to scale them down a little bit. You could have 5 calls to display each tile, each one specifying your desired scale (say 0.5), but this isn't a great idea. Whenever you find yourself duplicating the same piece of information, you might be able to better organize. By creating a variable that defines what scale you want your tiles to be, you now have a single place that you can change to affect all 5 displayed tiles. This saves you from having to track down every line that you use the now out of date variable.
The Importance of Variable Names
Often when first starting to program there is a tendency towards very quick and simple variable names, much like you'd see in an algebra class. X, y and z are favorite variable names, as are a, b and c. There are two major problems with this approach, that become more obvious the more complex your brains become.
First, these letters often tell you nothing about what information the variable is storing. While it may make perfect sense to you now, what if you spend the next week working on another aspect of your game before coming back to this brain. Every second you spend re-understanding the kode you wrote is a second you could have been spending improving your game. This is even more relevant if you ever want someone to take a look at your kode, whether to help you with it or to use it themselves. By having descriptive variable names it is easier for someone else to understand your thought process.
The second problem is that you run the risk of re-using a variable name. If you have a particularly large brain, split across several pages or even one massive page, you run the risk of forgetting that the variable is already in use, and overwritinng the information it was storing. Honestly, this is a risk even with more descriptive variable names, but the risk is much reduced.
Another point to make is that, no matter how long it is, you don't have to fully type in the variable name every time. You can either select your variable in the tile picker, or type the beginning of the variable name to filter.
The Power of Pages
Pages are a great way of organizing your brains. The most common use I've seen for them is to have completely different behaviors on separate pages, and switch your object's behavior using the switch page tile. This is a great use for pages, but you can do so much more. For example, what if both of your pages of kode share a lot of similarites...perhaps the camera and some of the controls? You can take the shared bits and stick them in a separate page and use call page from each of the main pages of your object. Doing this avoids needing to duplicate kode, which I'll talk about shortly. Sometimes, just using separate pages as a logical grouping of sections of kode can help make it easier to figure out what you were thinking when you wrote it, and figure out where you need to look to make a change.
Another potential use of call page for the advanced user is the ability to simulate function calls. If you have a common operation that needs to be repeated on multiple objects, you can set some variable values to simulate passing arguments, call the page that represents your function, and have the called page set its own variable(s) to simulate return values. The main problems with this approach are that there is no scope in Spark other than object scope and that there is no contract with the called page. This means that your called pages will be using the exact same variables found everywhere else in the brain, which allows this method to work, but means you have to be careful about modifying variables that may be used elsewhere. It also means that there is no obvious way to know what values the called page expects without going and reading through the whole page.
The Horror of Duplicated Kode
Something that is taught reasonably early on when learning to program is why you should try to avoid duplicating your kode at all costs. Duplicated kode is a maintenance nightmare. Always keep in mind that most of your kode is likely to be changed at some point in the future. Let's say you wrote some kode in a logic cube that told a goblin how to behave. Then you decided you wanted it to work on ten goblins, so you copied it nine times, giving a new goblin for the kode to work on each time. This is all well and good, until you realize that your behavior isn't quite as perfect as you first thought, and you now have to change this behavior ten times. Not only do you run the risk of missing one of the copied pieces of kode, you have given yourself 10 times the work.
Any time you find that your kode is almost the same as some other kode you wrote, it may be worth checking to see if there is some way to get the same behavior while only writing that common kode once.
Simpler is Usually Better
I once read an interesting article that claimed that one of the problems with programming is that it is easier to write code than it is to read it. Whether any of us are actually at that point in Spark or not, it is important to do everything we can to make our kode as easy to read as possible. Having easy to read kode is a bit more of an art than a science, and everyone will have their own preferences, but usually if you can achieve the same result with 3 tiles rather than 8, then the 3 tile method will be easier to read.
Just remember that if you have to think to remember what your line of kode is doing while you are working on it, you are going to have an even harder time remembering what it does after not looking at it for a period of time. Everything you can do to make it easy to remember what you were doing when you were koding something up is time well spent.
Use Object Templates
This goes back to the point of duplication, but if you have any object that is likely to be used more than once in your game, and each copy is expected to be the same, use a template. It is extremely common to change the behavior of an object as you start iterating on your game, and if you have twenty spawn points in your game, you really don't want to have to go change all twenty of them. By creating a template of your spawn point, and having all your spawn points create a copy of it, you will have a single spot to change.
The Importance of Debugging
The fact is that when you are koding, you are going to make mistakes, and unless you are a computer, sometimes those mistakes have consequences that you didn't expect. It is not uncommon to see some bizarre result from a seemingly unrelated change, so you need to be able to get better information about what is going on in your brain.
Most programming languages have debuggers to help you track down where things are going wrong, but in the absence of such a debugger in Spark, we fall back to the "printf" method of debugging. Your best friend here is the display tile, and everyone should spend some time getting familiar with it. By using the display tile, you can check the state of your brain at just about any point, to see what is really going on inside your brain, rather than assuming you understand.
In the same vein as naming variables, naming assemblies and characters is also important. Going into the properties you can change the name at the top of the properties. This will be useful to keep track of which 'in world picker' you have selected, so everything isn't 'woodland peasant male' or 'goblin', etc. You can even name logic cubes so that not all of them are "logic cube".
This helps you not only in the brains when looking at what item you have selected, but also can have some side benefits in the main editor. You can browse a list of your named objects and select them from the edit pause screen and you can also set an option to show object names in the editor, which makes it easier to figure out what is what.
Hopefully some of these tips can help folks out. Even if you don't immediately adopt them, I hope if you run into a situation where using one would have been beneficial you'll think back to this article, and perhaps reconsider.