GML Technical Debt - Best Practices Question

[samspade]

Anyone have any good tips for cleaning up projects? What qualifies as technical debt in your mind, what would you ignore? What would you fix?

 

[Yal]

I find this topic way too vague to have any discussional value. You should combine all your refactoring topics into one single topic with more than one OP sentence.

Technical debt is when you solve a problem by giving your future self a bigger problem. GM has had a lot of potential for this thanks to not requiring a lot of organization to get code to run, and two major breaking-changes transitions (GM8 --> GMS1, GMS1 --> GMS2) with lots of deprecation and major changes in what's the best approach to solve certain types of problems.

I'd ignore anything that doesn't create huge issues - tile_get_layer_find() compatibility scripts are GML loops over the entire tile array that are literally millions of times slower in my Soulsvania engine's GMS2 version than the compiled GMS1 lookup function, and I had to deal with that by creating my own lookup table of all tile IDs (since they're all on a grid anyway) to get it to run properly. All d3d_model_add_* functions are likewise a ton slower because of creating a lot of temp resources instead of reusing them. Not sure if it qualifies as technical debt, but it definitely makes the project perform worse in the future, so I guess you should deal with it.

 

[samspade]

I find this topic way too vague to have any discussional value. You should combine all your refactoring topics into one single topic with more than one OP sentence.

Technical debt is when you solve a problem by giving your future self a bigger problem. GM has had a lot of potential for this thanks to not requiring a lot of organization to get code to run, and two major breaking-changes transitions (GM8 --> GMS1, GMS1 --> GMS2) with lots of deprecation and major changes in what's the best approach to solve certain types of problems.

I'd ignore anything that doesn't create huge issues - tile_get_layer_find() compatibility scripts are GML loops over the entire tile array that are literally millions of times slower in my Soulsvania engine's GMS2 version than the compiled GMS1 lookup function, and I had to deal with that by creating my own lookup table of all tile IDs (since they're all on a grid anyway) to get it to run properly. All d3d_model_add_* functions are likewise a ton slower because of creating a lot of temp resources instead of reusing them. Not sure if it qualifies as technical debt, but it definitely makes the project perform worse in the future, so I guess you should deal with it.

While it is general, I don't think it is too vague. In thinking about this for the last week here are some of my answers to my own questions.

In general, my personal goal for my own code (beyond it working in the first place) is that:

• I should be able to understand it as fast as I can read it (and any attached documentation)
• I should be able to modify it with as little effort as possible

But these goals often conflict with:

• Working quickly
• Not knowing what I'm doing (both in the skill sense but also in the creative sense of sometimes you don't know what you're designing until you've designed it)
• The ever changing iterative process of designing a game itself

Resulting in (as you said) solving a problem creating a bigger problem down the road.

Here are some general categories of technical debt I come across in my projects:

• comments or code documentation out of date
• script jsdoc comments out of date
• dead and unused resources (scripts, objects, sprites, etc.)
• poorly structured and designed code
• poorly structured and designed systems
• minor, non game breaking, bugs I've been ignoring
• highly and unnecessarily interconnected code

A couple of these have pretty specific fixes which I try to routinely do:

• Review script jsdoc comments to make sure they exist and are accurate
• review comments and make sure they are accurate
• review code documentation and make sure it is accurate
• delete any unused resources (that's what source control is for)
• get around to fixing the tiny bugs, or at least understanding them better

The structured ones are a lot harder to do. What qualifies as bad structure or bad design? That said, I do have a couple things it seems I regularly do.

• Organize my resources by folder and make sure names are good
• If it is obvious that I have designed to similar parts of my game in entirely different ways (e.g. only half of my enemies use the enemy parent for no reason) I'll try to pick one design and go with that
• If I find it hard to remember how a thing worked when I come back to it I take it as a sign that it is either poorly designed or poorly documented. If poorly documented, I try to document. If poorly designed I try to redesign it
• whenever I struggle (even for a few seconds) what a variable does, I take it as a sign that it was poorly named and consider renaming it
• whenever I struggle to modify or extend areas of code I take it as a sign that they were poorly designed or documented and either redesign or (re)document them
• review code for unnecessary repetition or things which can be turned into scripts or consolidated through inheritance
• Occasionally just reading through the code of different objects to see what I see

Sometimes I do the above for small chunks of code, sometimes I stop all work on the project and do it for nearly the entire project as it currently stands (none of my projects are huge yet so this is still doable).

 

[Yal]

• Review script jsdoc comments to make sure they exist and are accurate

• review comments and make sure they are accurate

• review code documentation and make sure it is accurate

If your comments need to be changed when you update the code, you're writing them wrong. Comments should describe purpose, not implementation. You wouldn't believe how many useless comments along the lines of

a += 5; //Add 5 to a

I've seen in my days, and I've only been a professional programmer for like 4 years. Comments are much better if they tell you why you do something, the code itself is supposed to be readable enough that you don't need to comment every line to tell what it does. (Descriptive variable and function names goes a long way here, and let the compiler figure out how to optimize away useless middle steps for speed - these days it's better at it than you'll ever be)