[Wiz]

I wish to define naming conventions for a disassembly of Shining Force II.

I was planning to benefit from the sonic hacking community's experience by applying the naming convention from the disassemblies that are available at the SVN repository, but Sik just told me that they are actually different from a disassembly to another !

So, er ... I really don't know which conventions I should choose, and I don't even know if it matters that much !

Can anybody give me advice about it ? Thanks !

[ICEknight]

Aren't there a few original Genesis source codes around? Perhaps you should check if they're sharing some label names and such.


Good luck with disassembling the whole thing, by the way.

This post has been edited by ICEknight: 05 January 2009 - 06:31 PM

[FraGag]

I had this concern too when Hivebrain published his revised disassembly of Sonic 1, so I asked this question in the Community SVN Project forum, but got no reply.

It's a pretty subjective topic, so we must expect that some will not be pleased by the final decision (if we manage to get there). (I'm reminded of Tweaker, who disagreed with giving names for the RAM variables in the Sonic 2 disassembly, which were added by Xenowhirl.)

Then there's an obvious dilemma: should we use short and concise names, or long and descriptive names? Using names too short can make them cryptic, but using names too long can take up too much space and decrease readability. As for me, I prefer longer names, but with some abbreviations that appear often in the disassembly (e.g. "Obj"); shortening a word just to keep it within a predefined limit is something I dislike.

I'd like to hear more opinions on this topic, and I'm sure you wish the same, Wiz. If this topic doesn't get much more activity, you're bound to take the liberty to adopt the convention you personally prefer.

[Sik]

Firstly, it seems each of the disassemblies has its own naming convention. I mean, hell, the Sonic 3D disasm is literally using the same conventions I use when writing code, which is completely different from what the other disassemblies do!

Even yet we'd have trouble, because Sonic 3D works vastly different from Sonic 1 and 2 if I recall correctly - the latter make massive usage of objects and such, while the former not only doesn't know the concept of object outside something in a level, but even has some code for them completely outside the object structure (e.g. put two monitors together and get ready to suffer). How do you make a consistent convention that can be used with both situations?

[Hivebrain]

I wouldn't worry about naming conventions too much, as long as it's clear what something is. I'm quite fond of using prefixes (e.g "v_" for RAM variables, "ob" for object variables), which haven't been used at all in the S2 disassembly.

[Wiz]

Thanks a lot for the answers guys !!


Ok, I get it, there is not ONE best naming convention ; it's a bit contextual and it's better to elaborate it according to the way the game is structured.
Nice ! That's intuitive !

So actually, in order to find convenient conventions for Shining Force II, I just need to think about it myself ... and that's what I've done so far ! \o/

So yeah, I'll just stay confident with my current choices, though they are not that clear at the moment >_> ... I've named subroutines like "PlayMusic" (CamelCase I think), and other ones like "playMusic" (I'm a java programmer, I couldn't help it) ! I'll make everything like "PlayMusic", I think.


About the names length dilemma, I thinkwe don't need to set a length limit because in ASM, very long names don't affect readability that much. I mean, there usually must be something like a maximum of 2, maybe 3 names per line of ASM code, so you're not likely to reach you're screen's width limit that easily, right ? So yeah, I'm for long names to easily recognize stuff (since I'm more in a disassembly perspective than in a programming one), but tell me if my reasoning is wrong.


And I agree about prefixes, I've actually used stuff like p_ for pointers, pt_ for pointer tables, j_ for simple jumps (I think IDA does it automatically), and rjt_ for relative jump tables (Shining Force II uses a lot of that ... I don't know if that's the case in Sonic games)


Thanks again , I still hope there will be more discussion about naming conventions, because there may be smart naming ideas that not everybody has intuitively !


And yeah ICEknight, I plan (well, me and a very skilled SF2 hacking fellow) to totally disassemble SF2 and that will need time, but the Sonic community example totally gives hope !

[Sik]

Wiz, on Jan 9 2009, 05:57 PM, said:

About the names length dilemma, I thinkwe don't need to set a length limit because in ASM, very long names don't affect readability that much. I mean, there usually must be something like a maximum of 2, maybe 3 names per line of ASM code, so you're not likely to reach you're screen's width limit that easily, right ? So yeah, I'm for long names to easily recognize stuff (since I'm more in a disassembly perspective than in a programming one), but tell me if my reasoning is wrong.

Name length is pretty much an assembler problem really. Most building tools have limits on the name length. You're unlikely to find one with the 8 character size limit though - most likely you'll find 31 or something like that. So yeah, I'd stick with 31 characters maximum. Also local labels for things like @Loop makes things cleaner often.

[FraGag]

Wiz, on Jan 9 2009, 02:57 PM, said:

About the names length dilemma, I thinkwe don't need to set a length limit because in ASM, very long names don't affect readability that much. I mean, there usually must be something like a maximum of 2, maybe 3 names per line of ASM code, so you're not likely to reach you're screen's width limit that easily, right ? So yeah, I'm for long names to easily recognize stuff (since I'm more in a disassembly perspective than in a programming one), but tell me if my reasoning is wrong.

My concern was mainly about the comments at the end of the lines that may get misaligned, or require too much indentation to keep them aligned. On the other hand, I prefer naming things correctly so you can read the instruction and just "get it" without having to read a comment (if you're a bit familiar with how the game works).

Wiz, on Jan 9 2009, 02:57 PM, said:

rjt_ for relative jump tables (Shining Force II uses a lot of that ... I don't know if that's the case in Sonic games)

Sonic games often use offset tables, like this:

Syntax Highlighted Code: ASM

 

		[color= #00bfff;]move[/color].[color= #00bfff;]w[/color]	OffsetTable(pc,d0.[color= #00bfff;]w[/color]),d0

		[color= #00bfff;]jmp[/color]	OffsetTable(pc,d0.[color= #00bfff;]w[/color])

[color= #adadad; font-style: italic;]; ===========================================================================[/color]

 

OffsetTable:	[color= #00bfff;]dc[/color].[color= #00bfff;]w[/color] Offset1-OffsetTable

		[color= #00bfff;]dc[/color].[color= #00bfff;]w[/color] Offset2-OffsetTable

		[color= #00bfff;]dc[/color].[color= #00bfff;]w[/color] Offset3-OffsetTable

 

There's also a bra.w table for the game modes.

This post has been edited by FraGag: 09 January 2009 - 06:36 PM

[Wiz]

Ok I see, thanks for the precisions.

And yes FraGag, that's exactly the same mechanism we have in SF2 !