Page 3 of 4
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 4:22 am
by BigDumbDinosaur
If you're writing code you expect to be read mainly by people entirely unfamiliar with 6502 assembly language, a comment like the above might be exactly the right thing.
Your comment reminds me of an old joke about understanding programming languages.
- Assembly language was designed for people who are systems level programmers.
C was designed for people who think they are systems level programmers.
FORTRAN was designed for engineers who think they are programmers.
COBOL was designed for business managers who think they are programmers.
BASIC was designed for everyone else who thinks they are programmers.
C++ was designed for people who think Bill Gates invented the computer.
Joking aside, if someone is unfamiliar with any assembly language the going will be rough for them when they try to read and understand source code. One really has to at least have some understanding of the machine's instruction set in order to glean anything useful by doing so. Otherwise, it will all be gibberish.
A comment that says "decrement the X register" isn't helpful, and in reality is redundant—instruction mnemonics tell the programmer what they do. What is needed is a comment telling the reader why the X-register is being decremented. The reader can always crack open an assembly language manual to find out what the DEX instruction does. The program comments should be telling the reader what is going on, not what the assembly language statements mean. In other words, comments should be explaining what is being processed and how, not what the microprocessor is doing.
In more than a few of my programs, I may have many lines of commentary explaining what a subroutine is supposed to do, what kind of data it is processing, errors that may be generated. At the very least, there will be information about preliminary steps to carry out before calling the function, how the registers will be affected, and what error returns might come back. For example:
Code: Select all
;scsicmd: EXECUTE SCSI COMMAND
;
; ————————————————————————————————————————————————————————————————————————
; Preparatory Op: GPPTR must be set to the 24-bit address of the buffer
; that is to be accessed during the data in & data out
; phases. (1)
;
; Call registers: .A: target device SCSI ID
; .X: CDB address LSW
; .Y: CDB address MSW
;
; Exit Registers: .A: exit code (2)
; .B: $00
; .X: used
; .Y: used
; DB: entry value
; DP: entry value
; PB: entry value
;
; MPU Flags: NVmxDIZC
; ||||||||
; |||||||+———> 0: okay (2)
; ||||||| 1: exception (3)
; ||||||+————> reflects exit code
; ||||++—————> 0
; ||++———————> 1
; ++—————————> undefined
;
; Notes: 1) The buffer address is a "don't care" if the command to be
; executed doesn't return any data to the caller, other than an
; error code.
;
; 2) See 'include/error.asm' for the list of possible SCSI subsys-
; tem errors.
; ———————————————————————————————————————————————————————————————————————
Even though writing commentary may take a fair amount of time it has the value of permanency. I wrote all that eight years ago when I got SCSI mass storage working with my POC unit. I could never possibly remember all of the nuances of how SCSI processing works in my POC units without that sort of documentation. There are over 12,000 lines in the source code for the firmware. Without detailed commentary, I'd be faced with having to figure out what it was I intended when I wrote that clever-looking bit of code that I am now staring at eight years later.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 5:10 am
by barrym95838
... For example, here's a little routine with a fair amount of subtlety in it: ...
Using PL instead of CC to indicate a successful conversion is a minor stroke of genius! Saves three bytes and at least a cycle or a few over my best (untested) attempt ...
Code: Select all
asc2bin:
eor #$30 ; "0" = $00, "9" = $09
cmp #$0a
bcc done ; exit with cc for good digit
eor #$70 ; "@" = $00, "_" = $1f
and #$df ; fold in the "lower case"
beq done ; cs for "@" and "`"
cmp #$20
bcs done ; cs for not "alpha"
adc #$09 ; "A" = $0a, "_" = $28, cc
done:
rts
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 5:20 am
by cjs
...if someone is unfamiliar with any assembly language the going will be rough for them when they try to read and understand source code.
True. On the other hand, if you're demonstrating a small fragment of source code to someone who is familiar with one or more assembly languages, but not the particular one you're using (and perhaps not even any assembly languages similar to the one you're using), such a comment can be helpful.
This is why I say that, rather than trying to follow rules like "never, ever do this," consider what your audience needs and write for them.
A comment that says "decrement the X register" isn't helpful, and in reality is redundant—instruction mnemonics tell the programmer what they do. What is needed is a comment telling the reader why the X-register is being decremented.
I can easily think of situations where you're dead wrong about this. Consider a simple loop in 6502 assembly being shown to a CDC-6600 programmer not familiar with microprocessors. He'll know perfectly well what the DEX is being used for, once he understands what DEX does. Giving him generic information about how loops work in assembly language is telling him something he already knows, and not mentioning right there what 6502 DEX (which he has never seen before) does is forcing him to go elsewhere for a fairly trivial bit of information he doesn't know.
Focus on your audience, not on arbitrary rules.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 6:21 am
by GARTHWILSON
He'll know perfectly well what the DEX is being used for, once he understands what DEX does. Giving him generic information about how loops work in assembly language is telling him something he already knows, and not mentioning right there what 6502 DEX (which he has never seen before) does is forcing him to go elsewhere for a fairly trivial bit of information he doesn't know.
I suspect that if he doesn't know what DEX does, he probably also doesn't know what the X register is for. The functions of X and Y, maybe even A, might not be kept straight in the mind of someone so new to the 65's. They'll probably need to back up and pick up some basics.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 6:53 am
by BigDumbDinosaur
A comment that says "decrement the X register" isn't helpful, and in reality is redundant—instruction mnemonics tell the programmer what they do. What is needed is a comment telling the reader why the X-register is being decremented.
I can easily think of situations where you're dead wrong about this. Consider a simple loop in 6502 assembly being shown to a CDC-6600 programmer not familiar with microprocessors. He'll know perfectly well what the DEX is being used for, once he understands what DEX does. Giving him generic information about how loops work in assembly language is telling him something he already knows, and not mentioning right there what 6502 DEX (which he has never seen before) does is forcing him to go elsewhere for a fairly trivial bit of information he doesn't know.
Focus on your audience, not on arbitrary rules.
My audience?
Well, I guess I'm completely wrong because I'm an out-of-touch fuddy-duddy who started writing 6502 programs 43 years ago and therefore didn't know that when I comment my code I'm supposed to hold someone's hand because he can't be bothered to consult a reference source when he encounters something he doesn't know.
If your CDC-6600 programmer doesn't know what a particular machine instruction does, he needs to study available reference materials, which is how I and countless others of my generation learned the 6502 assembly language. That should not be a problem for any reasonably motivated person, as the 6502 is arguably the most documented microprocessor ever produced.
Programmers are paid to write functioning software, not teach school. Therefore, there is no reason to put comments in source code that, in effect, say water is wet and fire is hot. If someone new to a particular assembly language is too lazy to have a manual at hand as he studies code that has instructions with which he is not familiar then that's too bad.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 7:03 am
by cjs
...and therefore didn't know that when I comment my code I'm supposed to hold someone's hand because he can't be bothered to consult a reference source when he encounters something he doesn't know.
If your CDC-6600 programmer doesn't know what a particular machine instruction does, he needs to study available reference materials, which is how I and countless others of my generation learned the 6502 assembly language.
Well, you either can't imagine a situation where the primary purpose is not to teach someone to be an effective 6502 programmer or you feel that if that's not the primary purpose the problem at hand should be solved less efficiently than it could be. That's your choice, I guess.
Personally, while I have plenty of rules and guidelines, I have found it works better to focus on the problem to be solved and break the rules when they make that more difficult or inefficient.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 7:05 am
by BigDumbDinosaur
I suspect that if he doesn't know what DEX does, he probably also doesn't know what the X register is for. The functions of X and Y, maybe even A, might not be kept straight in the mind of someone so new to the 65's. They'll probably need to back up and pick up some basics.
That's exactly my point. At the risk of sounding repetitive, source code commentary should be explaining what the program does, not what the microprocessor does. If the bloke reading the source code doesn't know what the individual instructions do then, as you said, he needs to read up on that processor's instruction set.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 7:14 am
by barrym95838
... Well, I guess I'm completely wrong because I'm an out-of-touch fuddy-duddy who started writing 6502 programs 43 years ago and therefore didn't know that when I comment my code I'm supposed to hold someone's hand because he can't be bothered to consult a reference source when he encounters something he doesn't know.
Hey, if the hat fits, I can't fault you for wearing it with élan!
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 7:24 am
by BigDumbDinosaur
...and therefore didn't know that when I comment my code I'm supposed to hold someone's hand because he can't be bothered to consult a reference source when he encounters something he doesn't know.
If your CDC-6600 programmer doesn't know what a particular machine instruction does, he needs to study available reference materials, which is how I and countless others of my generation learned the 6502 assembly language.
Well, you either can't imagine a situation where the primary purpose is not to teach someone to be an effective 6502 programmer or you feel that if that's not the primary purpose the problem at hand should be solved less efficiently than it could be. That's your choice, I guess.
Personally, while I have plenty of rules and guidelines, I have found it works better to focus on the problem to be solved and break the rules when they make that more difficult or inefficient.
Who said anything about rules or anything about efficiently solving a problem? You're not getting what I am saying.
Programs are commented so anyone who is reasonably fluent in the language will understand what the program is doing. Programs are not commented to teach the language to the reader. Anyone who has worked in a production programming environment quickly learns that. That basic tenet has existed for longer than I've been writing software. It's a true today as it was in 1970 when I wrote my first machine code program.
Commentary has nothing to do with the efficiency of a program. So I fail to understand why you might think otherwise.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 7:25 am
by BigDumbDinosaur
... Well, I guess I'm completely wrong because I'm an out-of-touch fuddy-duddy who started writing 6502 programs 43 years ago and therefore didn't know that when I comment my code I'm supposed to hold someone's hand because he can't be bothered to consult a reference source when he encounters something he doesn't know.
Hey, if the hat fits, I can't fault you for wearing it with élan!
It's too bad we don't have sarcasm tags here.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 7:44 am
by barrym95838
Your comment reminds me of an old joke about understanding programming languages ...
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 8:20 am
by GARTHWILSON
LOL Then there's the "A Brief, Incomplete, and Mostly Wrong History of Programming Languages" which is quite humorous. One of the paragraphs:
1972 - Dennis Ritchie invents a powerful gun that shoots both forward and backward simultaneously. Not satisfied with the number of deaths and permanent maimings from that invention, he invents C and Unix.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 10:58 am
by cjs
Who said anything about rules or anything about efficiently solving a problem?
You provided rules. I was talking about efficiently solving a problem. You may disagree with doing the latter; there's probably not much point in arguing about that.
Programs are commented so anyone who is reasonably fluent in the language will understand what the program is doing. Programs are not commented to teach the language to the reader. Anyone who has worked in a production programming environment quickly learns that.
Again, lack of imagination here. Not all code is written for "production programming environments."
If you're the sort of person who insists that the code examples on a Wikipedia page intended to give someone an idea of the flavour of a language must be written for those who already know the language, you have completely missed the point of the code, and you'll write code that is bad for that particular purpose. You may dislike code like
this example, but that's good code with good comments because it better fulfills its purpose than what you're saying should be written.
This works the other way around, too. You mentioned that it's important to explain "why you're incrementing X," but often it's detrimental to do this. For almost all code designed to be read by reasonably experienced 6502 programmers, I would say it's bad (not horribly bad, but definitely not good) to add comments to someting like:
Code: Select all
inc curpos
beq +
inc curpos+1
+ ...
When your readers already know the pattern (or will very soon learn it and use it regularly), adding a comment as to why you're doing the
inc curpos+1 is a waste of your time and a waste of the reader's time and attention.
Commentary has nothing to do with the efficiency of a program. So I fail to understand why you might think otherwise.
Commentary absolutely has to do with the efficiency of a program when you account for costs beyond just the run time of the program. You yourself provided an example in your SCSI routine: why did you spend the extra time and effort on those comments, which were clearly a short-term cost? Because you were concerned about the overall efficiency of your software development effort in the long term, and you know it was likely to save you more time later than the time you'd spent earlier to write those comments.
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 12:46 pm
by BillG
A comment that says "decrement the X register" isn't helpful, and in reality is redundant—instruction mnemonics tell the programmer what they do. What is needed is a comment telling the reader why the X-register is being decremented.
I can easily think of situations where you're dead wrong about this. Consider a simple loop in 6502 assembly being shown to a CDC-6600 programmer not familiar with microprocessors. He'll know perfectly well what the DEX is being used for, once he understands what DEX does. Giving him generic information about how loops work in assembly language is telling him something he already knows, and not mentioning right there what 6502 DEX (which he has never seen before) does is forcing him to go elsewhere for a fairly trivial bit of information he doesn't know.
Most programmers will know what DEX means after seeing it a couple of times. After that, the comment becomes noise.
Some people believe that every single line in a program should be commented. That leads to having to make up trivial remarks.
In the following section of code, I do not comment the often used incrementation of a 16-bit value; it becomes obvious to anyone who has been programming much at all. But I do comment the range checks as the conditional branches on the 6502 are non-obvious at best.
Code: Select all
053A 18 [2] 00325 ChkLim clc ; Increment line number
053B AD 048B [4] 00326 lda LinNum
053E 69 01 [2] 00327 adc #1
0540 8D 048B [4] 00328 sta LinNum
0543 AD 048C [4] 00329 lda LinNum+1
0546 69 00 [2] 00330 adc #0
0548 8D 048C [4] 00331 sta LinNum+1
00332
054B CD 048A [4] 00333 cmp UppLim+1 ; Compare against upper line limit
054E 90 0C (055C) [2/3] 00334 bcc ChkLow ; Below, go check low limit
0550 D0 31 (0583) [2/3] 00335 bne Exit ; Above, we are done
00336
0552 AD 048B [4] 00337 lda LinNum ; Lower byte of number
0555 CD 0489 [4] 00338 cmp UppLim
0558 F0 02 (055C) [2/3] 00339 beq ChkLow ; At limit, go check low limit
055A B0 27 (0583) [2/3] 00340 bcs Exit ; Above, we are done
00341
055C AD 048C [4] 00342 ChkLow lda LinNum+1 ; Compare against lower line limit
055F CD 0488 [4] 00343 cmp LowLim+1
0562 90 0F (0573) [2/3] 00344 bcc SkipLn ; Below, skip this line
0564 D0 08 (056E) [2/3] 00345 bne DoShow ; Above, show this line
00346
0566 AD 048B [4] 00347 lda LinNum ; Lower byte of number
0569 CD 0487 [4] 00348 cmp LowLim
056C 90 05 (0573) [2/3] 00349 bcc SkipLn ; Below, skip this line
00350
056E A9 01 [2] 00351 DoShow lda #1 ; Set up to show this line
0570 8D 0485 [4] 00352 sta ShowLn
Re: Confused by Example ASM Program
Posted: Fri May 01, 2020 2:27 pm
by load81
Your comment reminds me of an old joke about understanding programming languages.
Somewhat extended:
- Pascal was designed for university professors who think they are programmers.
- Java was designed by a team who thinks memory leaks are normal and restarting the JVM solves every problem.
- Python was designed for everyone who is too young to have touched BASIC but thinks they're a programmer.
- Perl and Raku (ex-Perl 6) were designed by a mad genius who happens to be both a linguist and a programmer.
- Verlog and HDL were written by electrical engineers to intentionally baffle programmers.
I don't have anything pithy for C#, Rust, or Forth at the moment. I'm sure someone else can chime in.