Author Topic: A case for coding style convention.  (Read 445 times)

0 Members and 1 Guest are viewing this topic.

Offline m_dr_m

  • 464 Plus
  • *****
  • Posts: 327
  • Country: gb
  • http://orgams.wikidot.com/
    • OrgaMS!
    • Awards
A case for coding style convention.
« on: 19:37, 20 October 21 »

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:
Code: [Select]
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:
Code: [Select]
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.
like
0
No reactions

Offline Targhan

  • Supporter
  • 6128 Plus
  • *
  • Posts: 1.426
  • Country: fr
    • Awards
Re: A case for coding style convention.
« Reply #1 on: 21:18, 20 October 21 »
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?
like
1
Members reacted like:
m_dr_m,
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

Offline krusty_benediction

  • CPC6128
  • ****
  • Posts: 209
  • Country: fr
    • Awards
Re: A case for coding style convention.
« Reply #2 on: 22:16, 20 October 21 »
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)


Offline m_dr_m

  • 464 Plus
  • *****
  • Posts: 327
  • Country: gb
  • http://orgams.wikidot.com/
    • OrgaMS!
    • Awards
Re: A case for coding style convention.
« Reply #3 on: 14:40, 21 October 21 »
Good points, thanks.


Tastes 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.




[size=78%]I would follow another approach based on comment parsing[/size]

That's also a convention!



like
0
No reactions

Offline m_dr_m

  • 464 Plus
  • *****
  • Posts: 327
  • Country: gb
  • http://orgams.wikidot.com/
    • OrgaMS!
    • Awards
Re: A case for coding style convention.
« Reply #4 on: 14:48, 21 October 21 »
I 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)

like
0
No reactions

Online norecess

  • CPC6128
  • ****
  • Posts: 278
  • Country: ca
    • Awards
Re: A case for coding style convention.
« Reply #5 on: 16:37, 21 October 21 »
Few things that works well for me:

- I like prefixing all my macros with "_" and I use capitals.
Examples:
Code: [Select]
_CRTC 1, 50
_DISABLE_LOWER_ENABLE_UPPER_SET_MODE 0


- for labels I enjoy camel case notation, and use "_" to separate the scope
Examples:
Code: [Select]
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.
Code: [Select]
    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.
« Last Edit: 16:53, 21 October 21 by norecess »
like
0
No reactions

Offline zhulien

  • 6128 Plus
  • ******
  • Posts: 920
  • Country: au
  • aka Vorax
    • 8bitology
    • Awards
Re: A case for coding style convention.
« Reply #6 on: 17:21, 21 October 21 »

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/

« Last Edit: 17:23, 21 October 21 by zhulien »
like
0
No reactions