General Category > Programming

A case for coding style convention.

(1/2) > >>

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:

--- Code: ---INIT
InitTexture
[...]
.loopy
[...]
InitMesh
[...]
INTRO
[...]
TUNNEL
[...]
DOOM_INIT
[...]
DOOM
[...]
GRAND_FINAL
[...]
 
--- End code ---
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 > .loopyRegarding 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: ---FastPrintAt
; In: D = col
     ; E = row
     ; HL = nt string
    call set_location
; Enchaine
FastPrint_
; In: HL = nt string
[...]
--- End code ---
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?

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 22:16, 20 October 21 ---Tastes and conventions can change over time.
--- End quote ---
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 22:16, 20 October 21 ---[size=78%]I would follow another approach based on comment parsing[/size]
--- End quote ---

That's also a convention!



m_dr_m:

--- Quote from: Targhan on 21:18, 20 October 21 ---I am personally again lowercase labels
--- End quote ---
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)

Navigation

[0] Message Index

[#] Next page

Go to full version
Powered by SMFPacks Reactions Mod
Powered by SMFPacks Alerts Pro Mod
Powered by SMFPacks Mentions Pro Mod