I'm Spelos, and I'm the lead programmer of The Shadow of the Ramlord. In this development diary, I would like to talk about how we structure and organize our code, as well as keep it consistent throughout our codebase. While this article delves into the technicalities of programming, it also provides a few tips and suggestions to other developers or hobby mod creators. So let's get into it.
Amnesia's scripting language is very tightly coupled with Amnesia's API. That, unfortunately, means that a lot of proven methods of writing clean code do not apply. That is why I decided to write a derivative standard that tries to implement as many clean code principles as possible while keeping script files light and easy to read. The standard is public and you can find it HERE. This public standard goes into details of both styling and form of script files and proposes one of many possible structures.
Programmers read their code much more than they write it. Amnesia mod developers read Script_Functions part of the wiki much more than they read their code. Why is that?
It is because Amnesia modders have to interact with the API that Frictional Games designed. Your script is a plugin for Amnesia. That's why all of the code is dependant on Amnesia's internal signatures. Is Amnesia's API well written? Absolutely not. Can we work around it? Yes, we can.
A good example of the type of enhancement that we do to improve code readability is long function signature commenting. Take for example this extended function for creation of a particle system.
CreateParticleSystemAtEntityExt("BlueDust", "DustCloud.ps", "DustArea", false, 0.3f, 0.9f, 0.3f, 1.0f, true, 1.0f, 0.5f, 5.0f, 6.0f);
Granted, this is an extreme example, but it demonstrates the problem in a nice way. You see that 'false' boolean that's the fourth parameter? What does it do? And how does it differ from the ninth 'true' boolean? What are the floats on about?
Chances are, you would consult the all-knowing FictionalGames Wiki. What happens to a programmer when she needs to consult documentation in the middle of an algorithm? She loses flow, gets distracted, annoyed even.
We cannot completely get rid of this problem without abstracting the whole API, which is not an option given you cannot easily include other scripts inside your own and copying a few hundred lines into each of your script files isn't a good solution. And so we solved this potential issue by forcing an 80 character limit on a line and parameter comments for functions with long signatures. I mean, look for yourself, doesn't this look better?
You can now confidently say what those booleans do. And while some people would swear with their life that they remember all these parameters, since they're expert modders, I would argue that readability has more advantages.
Look at the color parameters. What color is it closest to? Green, yes. Now tell me, why is a "BlueDust" particle green? It is a bug, yes. Would you ever notice in the previous example? Most likely in the game when you see that the dust is green. Then you would go into the code look at the large function and... Well, you'd probably check the wiki to see what those parameters do. But in the readable version, you take a look at the color, go "Yep" and fix it within a few seconds.
There is a ton of small little improvements you can do to ease your development and save yourself from dealing with terrible issues. Most of these are not even specific to AngelScript. I would highly recommend a book by Dustin Boswell and Trevor Foucher called "The Art of Readable Code". There is a free online version. It includes a lot more great tips for improving your programming and making it more human-friendly.
After all, programming with other people is the best way to improve, have fun, and make something awesome together.