Welcome back to your programming blog. This is the first in a series of posts where I will discuss the AGK Studio tool and the programming tasks related to the new version of my game.
In the previous post, AppGameKit Studio – Let’s Begin, I mentioned that to update my game, I decided not to start from scratch but instead to build upon the existing codebase. My plan was to organize and structure it, remove what wasn’t useful, and keep what was.
This time, I will share what I found when reviewing my code and what activities emerged from my findings.
Time to dust off!
It only takes looking at three source code files to find many flaws—typical of a novice developer working without guidance, lacking organization, rushing through tasks… and during sleepless nights (which is exactly how the game was created).
File Naming Convention
When naming the source code files, I mixed languages. Some have names in Spanish, while others are in English.
Some files have explicit and complete names (pantalla_principal), while others are abbreviated (config).
I thought it was very «original» to label files containing functions—essentially, just libraries—as soporte («support»).
Even though I have files that contain functions meant to support the program, I felt some functions didn’t fit within them, so I casually created a new file and cheerfully named it util.
Function signatures
All functions should have a signature like the one shown in this image.
The signature must include the function’s name, the parameters it takes, and an explanation of what each parameter means, as well as a description of what the function does.
Unsurprisingly, there are functions that lack this. And guess what? Without looking at the code, I have no idea what those functions do.
In addition to that, the function names have various issues:
- Some start with f_ and others with fn_.
- There’s a mix of Spanish and English.
- The function name doesn’t always describe what it does. For example, f_mensaje_tutorial might seem like it retrieves or processes a text string, but in reality, it’s used to open a dialog and display a message inside.
Global variables and constants naming convention
Global variables don’t follow a standard. I decided to use a g at the beginning of the variable name to indicate that it’s a global variable. However, not all global variables include the g, and they’re sometimes declared in uppercase or lowercase letters, depending on how I felt at the time.
I also have constant and global variable declarations in a file that’s supposed to only contain global variables, and there are global variables created in other files as well.
As if that weren’t enough, in addition to mixing constants and globals, I also placed custom data type declarations within the global variable declarations. The custom type declarations don’t follow a standard either.
Variables naming convention
In this section, I found two practices. The good one is that I consistently followed a standard of using underscores to name variables, for example:
- nombre_archivo
- lb_archivo_existe
The bad practice is that I mixed two styles. Just as I used a g at the beginning of global variable names, I used an l (lowercase L) to indicate a local variable. However, I found local variables both with and without the initial L.
At some point, I probably thought it was unnecessary to add the L since all non-global variables were local, making the L redundant. Whatever the reason, after changing the standard, I didn’t update the code accordingly.
Function responsibilities and code length
In the book Becoming a Better Programmer: A Handbook for People Who Care About Code, which I will soon tell you more about, one of its chapters mentions (with which I completely agree) that, in principle, functions within programs should do one thing and do it well. It is considered bad practice for a function to perform two or more tasks. Additionally, regarding their length, the book suggests that functions shouldn’t be too long in order to enhance readability and maintainability. In Catastrophe‘s source ode, I did the opposite.
This screenshot shows parts of the main function responsible for a game session. Notice that it starts at line 1055 and ends at line 2196, more than 1100 lines of code. I’m not lying when I say that modifying this function was always a task I preferred to avoid; in fact, this function is the reason it took me so long to update or add functionality to the game.
This function is extremely long precisely because it performs many tasks. Although it’s part of the game engine, I thought it would be a good idea for it to handle displaying the challenge selection menu depending on the game mode. You can see this in the screenshot to the right.
In addition to displaying the game menu, the function also prepares the board and the control variables that will be used to bring the game to life.
The function also sets up and animates the game board on the screen.
To top it off like the champion within the code, the function validates whether the game ended in a win or loss for the player, displays the corresponding message on the screen, and frees up the resources used to set up the board.
Game data management
Like other skill-based games with levels, Catastrophe also keeps track of progress in the game. This is done through text files where the completed levels are recorded, and as part of the saved data, the number of moves and the time taken to solve the challenges are also stored.
Although they are related, the number of moves and the resolution time are stored in separate files.
In 2013, when I created the first version of the game, as far as I knew, the only option was to read and write plain text files, without any structure like XML or JSON. This, along with the lack of experience with the tool, led me to handle separate files for data that is interrelated.
What’s next and where does AGK Studio take part?
After reviewing the entire source code, in order to use the existing code as the foundation for the next version, the first tasks are undoubtedly:
- Renaming source code files
- Relocating global variables, constants, and custom data types into their corresponding source code files, one for each category
- Organizing functions into their appropriate files and renaming them to reflect what they do
For these three aspects in particular, AGK Studio provides the following tools:
The IDE
Like any modern IDE, it shows us a solution component manager, from which we can add, delete, and rename source code files.
Similarly, when inside a function’s body, we can see from the IDE which variables and constants are declared within that function. This is extremely useful for debugging and restructuring, as we can identify repeated variables and constants.
In the case of assets and support files, we can also view them from the IDE without needing to leave the program to see them in the file manager.
Capability to use JSON
With this version of the product, it is possible to read and write JSON files. This adds a great deal of flexibility to the tool.
From the start, game tracking and configuration can now be done in structured text files.
Access to JSON also allows interaction with web services that exchange data using that structure.
I have already done some tests for reading and writing JSON, and it works perfectly.
Use of 3D objects and space
It is not in my plans to make Catastrophe go in this direction (at least for now), but if the need arises, AGK Studio provides more and better tools for working with 3D environments. I already tested loading and texturing an object created in Blockbench. This functionality isn’t exclusive to AGK Studio, it was available since AGK V2, but I do see more and better extensions to the programming language in this area.
As you can see, there is plenty of work to be done. In the coming days, I will reorganize the code and publish an article on this, your trusted blog, to update you on the progress.
See you soon!
Deja un comentario