Improve labels

[RappyPhan]

If there's one thing most of us agree on, it's that the labels used in these disassemblies could be improved. Let's use this issue to decide what to do.

As I've already mentioned, I'd like to use the official labels that we have unearthedover the years. I think the main benefit would be that it gives us a common reference for variables and functions used in these games. This wouldn't only be useful to harmonise labels used across disassemblies, but it would also be a useful reference for documentation that talks about these. Authors wouldn't need to worry about which custom label they've used to queue a sprite for display, for example (Display_Sprite? Queue_Sprite?).

Discuss!

[GerbilSoft]

I'd suggest creating a GitHub Discussion about this instead of an issue, but it seems Discussions aren't enabled on the repository, and even though I have access to some functions in the sonicretro organization, I can't access project settings...

[devon-artmeier]

Copy and pasted from Retro:

A lot of the original names from the source code are not exactly clear about what they do (i.e. "actionsub" is used to queue an object for drawing, and "frameout" is used to delete an object). On top of this, there's oddities such as chunks being called "map", the stage layout buffer in RAM being called "mapwk", and the stage layout data in ROM being called "zone" or "zonemap". Then there's goofy things like 2 separate variables being called "waterflag" (flag that is set when the entire screen is underwater) and "water_flag" (water events routine ID), and other names like "swdata" (controller data), "pl_suu" (life count), "emy" (enemy), "emie" (Amy Rose), "masin" (animal capsule), "bobin" (bumper), "shima" (platform), "sjump" (spring object), "et" (robot generator from Sonic CD), "bs00b0" (Angel Island act 1 miniboss), "friend_suicide" (function to remove animals in the bad future in Sonic CD), etc. Using these names in the actual code would result it using a messy mixture of Japanese romanization, poorly translated English, over-abbreviation, terms that don't immediately make sense when reading, and sometimes nearly duplicate names for stuff that do different things. Even trickier, some functions use duplicate names (i.e. Amy has her own "speedset" function), which was possible, because a linker was used, and could just cherry pick XREFs. As it currently stands, none of the disassemblies use a linker, so you can't even do that without massive refactors first.

I think it would just be better to develop our own standards for code syntax and names, and leave the official source code names as bonus documentation when describing functions and variables. It also doesn't help that we don't even have a complete list of official names anyways (we're not even close, and this also includes things like local labels), so if you were to use them, you'd still need to come up with your own names for the rest, and the idea of using official names mixed in with custom names that attempt to fit in with the syntax style does not sound appealing at all. It would just blur the line between which names are official and which are made up, which is terrible for documentation purposes. I'm not opposed to using the official names as a reference to understand the original intentions of the programmers, but I think code readability is important, especially to those who haven't a clue about what the original names are supposed to mean. Both consistency and readability should be accounted for. Just because it's consistent, doesn't mean that it's necessarily good for the purposes of the disassemblies. The official names were just not designed for documented open source code and shouldn't be treated as such.

[Brainulator9]

In addition to what @devon-artmeier said, I wouldn't mind translating/calquing certain names to better align with known source code names:

• SpinningLight = signal -> Signal
• LabyrinthConvey = kassya -> Pulley
• Various names for boss routines in Sonic 3 & Knuckles, such as bs00b0_die0 -> Obj_AIZMiniboss_Die0

Some of these may be controversial, though.