News:

Printed Amstrad Addict magazine announced, check it out here!

Main Menu
avatar_m_dr_m

A case for coding style convention.

Started by m_dr_m, 17:37, 20 October 21

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

m_dr_m


I'd like to leverage our collective brain to setup some convention about lowercase vs uppercase, prefix & co in assembler programs.
Issue 1: Taste differs and you can pick any convention since only consistency matters.
Issue 2: Risk of bikeshedding ahead.


Yet, some formalism could open new features in editors:
• Quick access to main sections / routines.
• Navigation path (see exemple below).


First, the concept of sections: labels that have just a documentation role, separating the big areas of the source.
For instance, in a DEMO, we could imagine:

INIT
InitTexture
[...]
.loopy
[...]
InitMesh
[...]
INTRO
[...]
TUNNEL
[...]
DOOM_INIT
[...]
DOOM
[...]
GRAND_FINAL
[...]

Then:

       
  • 1/ A shortcut would show a table of content (INIT/INTRO/TUNNEL/...). Informal bookmarks.
  • 2/ The current position in the source could be shown in the status bar. INIT > InitTexture > .loopy
Regarding the consistency, we could use case and/or prefix to visually discriminate the different usages of a label,.
Exemple:

       
  • * section: TESTS
  • * table  (aka R/O buffer):   WAVE01 = &bc00
  • * buffer (aka R/W table):  COMPLETION = &9300
  • * constant:  DOTS# =
  • * variable: new_filename  SKIP MAX_FILENAME_LENGTH+1
  • * macro:  SET_CRTC(reg,val)  (1)
  • * both entry point + chaining (cannot be moved) FastPrint_  (2)
  • * exported routine InitPlayer
  • * private routine  initfreq
(1) Macro case doesn't matter much since the assembler checks you don't CALL a macro or use it as a constant, but uppercase is a reminder something special is going on.
(2) Sometime I chain some routines, like that:

FastPrintAt
; In: D = col
     ; E = row
     ; HL = nt string
    call set_location
; Enchaine
FastPrint_
; In: HL = nt string
[...]

The risk is to move 'FastPrint' without noticing the code before.

Targhan

I am personally again lowercase labels, which can become unreadable.

Section is a "good idea", but tend to think that if you need sections, you should use several files with one section each!

But if I have to separate sections, I would use full lines of "--------" delimiter to separate them well.
What about ";-------- INTRO", with the "--------" marking your informal bookmark?
Targhan/Arkos

Arkos Tracker 2.0.1 now released! - Follow the news on Twitter!
Disark - A cross-platform Z80 disassembler/source converter
FDC Tool 1.1 - Read Amsdos files without the system

Imperial Mahjong
Orion Prime

krusty_benediction

Tastes and conventions can change over time. It is risky to build tools that rely on that.
I do not like a lot the exampleINIT
InitTexture
because there is no reason for me to say that InitTExture is a child of INIT
I would prefer
module INIT
InitTexture
endmodule

or something similar
There is no reason too to put  all these labels in the same files; each of them could be split in its own file
(BTW, I guess orgams can do that with its import syntax, no ? Mine is supposed to https://github.com/cpcsdk/rust.cpclib/blob/master/basm/tests/asm/good_include3.asm)
a table can also be a label without any directive after. How do differentiate it from a section ?

I would follow another approach based on comment parsing. You add some semantic to your labels thanks to the comment that preceded it (as for any modern langage and its documentation tooling suite)


m_dr_m

Good points, thanks.


Quote from: krusty_benediction on 20:16, 20 October 21Tastes and conventions can change over time.
I kind of like Python's convention of prefixing privates variables by _.
Saner in my book than 'protected' keyword, and then 'friend' keyword because you need to access it after all (in companion structure or unit tests...).
I kind of like Erlang's convention of prefixing unused variables by _. Especially useful combined with pattern matching.




Quote from: krusty_benediction on 20:16, 20 October 21[size=78%]I would follow another approach based on comment parsing[/size]

That's also a convention!




m_dr_m

Quote from: Targhan on 19:18, 20 October 21I am personally again lowercase labels
Well you can use snake_case. Too much all uppercase looks awful as well.
Actually, the more local a label is, the less intrusive it should be (short and unencumbered).

My brain hasn't been corrupted by java.
I prefer:
  MACRO CRTC_SET(reg, val)
  MACRO MAX(X, Y)
to:
  MACRO CRTC_SET_REGISTER(ctrc_register, ctrc_value)
  MACRO MAXIMUM(OPERAND_1, OPERAND_2)


norecess464

#5
Few things that works well for me:

- I like prefixing all my macros with "_" and I use capitals.
Examples:

_CRTC 1, 50
_DISABLE_LOWER_ENABLE_UPPER_SET_MODE 0



- for labels I enjoy camel case notation, and use "_" to separate the scope
Examples:

DrawColumn_HorizInit
DrawInt_End


Regarding code sections, I admit I mostly rely on folder usage in file system.
In my source codes, you can often see INCLUDE statements in middle of something.

    INCLUDE "Code/Game/AsicSprites/BossFight/BossFight_UpdateRingSprite.asm"

I do that for one big reason: fuzzy search. You know, when in your text editor / IDE / whatever, you can type few letters and then filenames appear (following your search)..
This allows me to navigate easily in the asm project.

But, as already mentioned ealier, we all have our own habits ; and workflows that work for some, will never work for others.
My personal website: https://norecess.cpcscene.net
My current project is Sonic GX, a remake of Sonic the Hedgehog for the awesome Amstrad GX-4000 game console!

zhulien

#6

I am willing to conform if we can agree, but i need to cater for the below scenarios in a consistent manner.

for classes, <classname>:

for methods of a class, <classname>_<methodname>:

for methodvariables, <classname>_<methodname>_<variablename>:

for class variables, <classname>_<missingmethodname>_<variablename>:, i.e. <classname>__<variablename>:

for exit labels for iterations or conditions, suffix _<number>_e:

for start of iterations, suffix _<number>_s:

If handcoding assembler I try to be consistent but I seldom am.

https://8bitology.net/poc/jscompile/

Powered by SMFPacks Menu Editor Mod