Page 1 of 3
Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:06 pm
by PeterJ
Hi,
Can I ask about formatting code?
I appreciate the 'proper' way of doing it is like the example below (This example of for InkSpector):
Code: Select all
TARGET ZXSPECTRUM48
SAVETAP "sc.tap"
ORG $6000
main: ld a,2
call 5633
loop: ld de,string
ld bc,eostr-string
call 8252
jp loop
string defb 22,10,10,17,5,72,69,76,76,79,32,87,79,82,76,68,33
eostr equ $
END main
However, Pasmo is far more relaxed about formatting, and this runs just fine:
Code: Select all
org $6000
main
ld a,2
call 5633
loop
ld de,string
ld bc,eostr-string
call 8252
jp loop
string defb 22,10,10,17,5,72,69,76,76,79,32,87,79,82,76,68,33
eostr equ $
END $6000
I understand that the first line is much better in terms of readability, but having to tab after every line is a bit of a pain.
Any thoughts from others on this?
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:09 pm
by chilledgamer
Of course I am new and cannot comment on proper formatting, but just thought I would let you know something I found out recently.
I am now using VSCode. and I can highlight as many lines as I want with the mouse and press tab, and it just works
. I'm sure you already new this , but just in case :d
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:18 pm
by Einar Saukas
Properly organizing and documenting source code is done for your own convenience, not for the assembler/compiler.
You don't HAVE to do it. But good luck trying to do something useful without doing it
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:21 pm
by PeterJ
I'm all for documenting [mention]Einar Saukas[/mention]!
Thanks [mention]chilledgamer[/mention], I use that with Python on Visual but just tend to use notepad for my z80.
It's just interesting how some assemblers actually force good formatting on you.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:25 pm
by Dr beep
I would not only go for the outlined version for readability, but also add all kinds of comment so after years you still can figure out what it exactly does.
To give you an example, I have a project, started 2011, bug found after 2 years and took me untill 2016 to find what went wrong.
Code itself is perfect but the stack of records grew over the program. i had to replace piece of code. Why code is placed at #6000 and not At #8000 is now explained in commentlines.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:26 pm
by Seven.FFF
Sometimes it is for the assembler. Some assemblers have rules that anything starting in column 0 is a label, and anything in columns 1+ is an opcode. Some assemblers allow reserved words as labels without trailing colons provided they are in column 0.
Basically the simpler the parser, the more likely you are to break its assumptions and produce uncompilable or wrong code if you don't follow its formatting rules. There are some real doozies out there with simplistic parsers.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:28 pm
by PeterJ
Just to add, I do normally include comments. I didn't in my sample as I didn't want to loose focus from the formatting angle. Cheers.
Thanks [mention]Seven.FFF[/mention]. Pasmo must be pretty clever to workout my dummy coding!
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:34 pm
by Morkin
One suggestion that I found useful when I was using ZX Spin is to always put a colon (:) at the end of labels, so I could use CTRL+F to find them (including the colon).
Without the colon, once the code got quite big I was encountering loads of matches, e.g. in LD statements, before I got to the label itself when I did CTRL+F.
Other assemblers may have ways to find labels in another way, but after a while it's easy to end up with hundreds of labels, so even an alphabetical list takes a while to scroll through especially if a lot of labels are similar.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:41 pm
by PeterJ
Thanks [mention]Morkin[/mention],
I know a lot of people quite rightly love Spin, but because it's so long in the tooth now I have problems with it in W10 (I know it's fine for some users).
At the sort of length code I do, notepad and Pasmo is fine for me, but that functionality with labels is useful. I will start using colons though so I can find labels in notepad.
Maybe one day we will get Spin V2 [mention]ZXDunny[/mention]? Here's hoping.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:42 pm
by ketmar
mine is usually like this. labels are always on a separate line, and instruction arguments are always at column 8. in-line comments are either at column 16 (if it fits), but almost always aligned.
Code: Select all
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; build fully unrolled screen blitter
;; generates 4329 bytes of code
;; blitter timing is 35897, so we can avoid DI/EI
;; in:
;; nothing
;; out:
;; all registers are dead
;; all alternate registers are dead
;;
VScrBuildBlit:
ld de,CodeEnd
exx
; start of vscr
ld hl,V_ADDR+1
; start of scr$+width/2
ld bc,scraddr8x8(4,1)+VSCR_WIDTH/2-1
; start of attr+width/2
ld de,scrattr8x8(4,1)+VSCR_WIDTH/2-1
exx
; put prologue
ld hl,blitjit_prologue
ld bc,blitjit_prologue_len
ldir
ld a,VSCR_HEIGHT
.jitnext9:
ex af,af'
; put scr$ copy parts (8 lines)
ld b,8
.jitnextvline:
push bc
Code: Select all
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; draw sprite with 16x8 tiles, with full-tile clipping
;; in:
;; B: y (chars)
;; C: x (chars)
;; HL: sprite data
;; out:
;; all main registers are dead
;; AF': dead
;; visible vscr starts at (4,1)
;; size: (24,12)
;;
DrawSpriteSimple16xn:
; horizontal clip
ld a,c
cp VSCR_WIDTH
ret nc
; vertical clip
ld a,b
cp VSCR_HEIGHT
jp nc,.checkneg
ld a,(hl) ; block counter
add a,b ; end y
sub a,VSCR_HEIGHT+1
ld a,(hl) ; most of the time it will be ok
; if the result is positive (or zero), we're ok
jp m,.vertok
; fix counter
ld a,VSCR_HEIGHT
sub b
.vertok:
ex af,af'
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:44 pm
by PeterJ
ketmar wrote: ↑Thu Jul 02, 2020 2:42 pm
but almost always aligned.
Thanks for the sake of my OCD, it must be aligned always!
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:48 pm
by ketmar
PeterJ wrote: ↑Thu Jul 02, 2020 2:44 pm
ketmar wrote: ↑Thu Jul 02, 2020 2:42 pm
but almost always aligned.
Thanks for the sake of my OCD, it must be aligned always!
and it is also easier to quickly scan the code too. syntax highlighting helps too, but with aligned parts it is even easier. this habit (aligning) actually came from GENS assembler (it did it automatically for you).
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 2:53 pm
by catmeows
Basically what everybody says:
1) comment, comment, comment ...
2) align by columns
3) meaningfull labels
Code: Select all
dutyModification
ld a, (ix + DUTY)
ld c, (ix + DUTYDELTA)
add a, c ;add duty change to duty
bit 7, c ;is delta negative ?
jr nz, negDutyDelta
ld b, (ix + DUTYMAX) ;compare with max duty
cp b
jr c, noDutyChange ;will not change duty delta sign
dutyChange
ld a, c ;negate duty delta
neg
ld c, a
ld a, b ;and set min/max limit as duty
ld (ix + DUTYDELTA), c ;store new delta
noDutyChange
ld (ix + DUTY), a ;store new duty
ret
negDutyDelta
ld b, (ix + DUTYMIN) ;compare with min duty
cp b
jr nc, noDutyChange ;will not change duty delta sign
jr dutyChange
noteModification
ld a, (ix + NOTELEN) ;decrease note length
dec a
ld (ix + NOTELEN), a
noteNoLastTick
ld a, (ix + ARPFLAG) ;is appergio enabled ?
or a
jr z, noteNoArp ;no
ld a, (tickCounter) ;if appergio enabled
and 1 ;every second tick play tone one octave higher
jr z, noteNoArp
ld a, 12 ;octave plus
noteNoArp
add a, (ix + BASENOTE) ;add nothing or octave to base note
call getNoteFreq ;get note frequency
ld a, (ix + VIBRATOFLAG)
or a
jr z, noteNoVibrato ;no vibrato
ld de, 47 ;1 + 11*2 = 23
add hl, de ;move note
ld a, (hl)
inc hl
ld h, (hl) ;get frequency for note+1
ld l, a
or a
sbc hl, bc ;difference between notes to HL
ld a, (ix + VIBRATODEPTH)
vibratoDepth
srl h
rr l
dec a
jr nz, vibratoDepth ; delta of frequency / ( 2^vibratoDepth)
ld a, (vibratoCounter) ; now multiply vibrato depth by vibracounter
or a
jr z, noteNoVibrato ;level 0
ld d, h
ld e, l
bit 1, a
jr nc, vibratoBit1
add hl, hl
vibratoBit1
rra
jr c, vibratoBit0
add hl, de
vibratoBit0
add hl, bc ; add vibrato to base note frequence
ld c, l
ld b, h
noteNoVibrato
ld a, (ix + PORTAMENTOFLAG)
or a
jr z, noteNoPortamento ;no portamento
ld e, (ix + PORTAMENTOLO)
ld d, (ix + PORTAMENTOHI)
ld l, e
ld h, d
add hl, bc ;add portamento to frequency
ld c, l ;store final frequency
ld b, h
ld l, (ix + PORTAMENTODELTALO)
ld h, (ix + PORTAMENTODELTAHI)
add hl, de ;update portamento
bit 7, (ix + PORTAMENTODELTAHI) ;is delta negative ?
jr z, notePortamentoChange
ccf
notePortamentoChange
jr nc, notePortamentoContinue
xor a ;switch portamento off
ld (ix + PORTAMENTOFLAG), a
notePortamentoContinue
ld (ix + PORTAMENTODELTALO), l ;store portamento delta
ld (ix + PORTAMENTODELTAHI), h
noteNoPortamento
;BC is final frequency
ld a, (ix + RELEASEFLAG)
or a
ret z ;if not release then exit
ld a, (ix + NOTELEN)
or a
ret nz ;is last tick ?
ld bc, 0 ;erase frequency for the very last tick
ret
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 3:59 pm
by Ralf
I do both ways.
When coding for Spectrum I never use automatic formatting, I always do it my own, (sometimes inconsistent
) way.
When I have short labels I May do
Code: Select all
DS1 LD A,(HL)
INC HL
DS2 LD B,(HL)
But what if I have a label like
CopyEnemyGraphicDataToBuffer ?
And yes, I use this kind of labels too, we may have this comfort, it's 2020.
Imagine typing these all spaces/tabs with each instruction:
Code: Select all
CopyEnemyGraphicDataToBuffer LD A,(HL)
INC HL
LD B,(HL)
So in case of long labels I prefer
Code: Select all
CopyEnemyGraphicDataToBuffer
LD A,(HL)
INC HL
CopyEnemyGraphicDataToBuffer 2
LD B,(HL)
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 4:03 pm
by Ralf
I would just strongly advise keeping komments aligned:
LAZY AND BAD:
Code: Select all
LD C,D ;comment1
LD A,(PlayerStatus) ;comment2
GOOD:
Code: Select all
LD C,D ;comment1
LD A,(PlayerStatus) ;comment2
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 4:09 pm
by PeterJ
I know it doesn't make a jot of difference to the assembler, but it's interesting how some of you are using uppercase, and others lowercase.... Just be consistent I suppose is the answer.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 4:16 pm
by Seven.FFF
Again it may make a difference, as some assemblers will treat a reserved word as an opcode if it’s entirely upper or lower case, but allow the same reserved word as a label if it is in mixed case.
Also some editors and IDEs detect the intent of the current line, and will auto-indent the next line by the same amount when you hit enter, so having a large indent optimised for long labels doesn’t cause more effort.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 4:17 pm
by Ralf
I know it doesn't make a jot of difference to the assembler, but it's interesting how some of you are using uppercase, and others lowercase.... Just be consistent I suppose is the answer.
It's called
S T Y L E
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 5:22 pm
by Stefan
IN THE OLD DAYS UPPERCASE WAS USEFUL SINCE LOWERCASE LETTERS COULD BE HARDER TO READ, THESE DAYS, UPPERCASE IS JUST CONSIDERED SHOUTING!!!!
(yes I grew up from uppercase to lowercase).
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 5:44 pm
by kolbeck
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 5:51 pm
by PeterJ
Excellent [mention]kolbeck[/mention]
I haven't laughed so much in months.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 5:57 pm
by andydansby
My preference has been for camelCase, just easier on my eyes.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 6:00 pm
by kolbeck
PeterJ wrote: ↑Thu Jul 02, 2020 5:51 pm
Excellent @kolbeck
I haven't laughed so much in months.
One of my favorite episodes
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 7:48 pm
by ketmar
as for me, i just can't remember how to type those big letters. have to copy-paste them from a premade text file.
Re: Suggestions on formatting of code
Posted: Thu Jul 02, 2020 8:34 pm
by Ast A. Moore
Okay, the video was brilliant!
Now, to address some of Peter’s concerns. Many text editors that are tailored to programmers will do a few things for you to make your life easier. For one, they provide syntax highlighting (not the editors themselves, but their extensions). Take a look at the one I wrote for TextMate:
Second, TextMate (and many others) will automatically tabulate your code. Once you’ve started a line with a tab, when you press Return, the next line will be automatically tabulated to line up with the line before. I don’t know what text editor you use, but I know that the reason I switched to TextMate from TextEdit (the macOS version of Notepad) and wrote the Z80 syntax highlighter was precisely because of these two problems: code readability and tabulation.