Confused by Example ASM Program

[BigDumbDinosaur]

cjs wrote:

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.

[barrym95838]

cjs wrote:

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

[cjs]

BigDumbDinosaur wrote:

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

Quote:

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.

[GARTHWILSON]

cjs wrote:

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.

[BigDumbDinosaur]

cjs wrote:

BigDumbDinosaur wrote:

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.

[cjs]

BigDumbDinosaur wrote:

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

[BigDumbDinosaur]

GARTHWILSON wrote:

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.

[barrym95838]

BigDumbDinosaur wrote:

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

[BigDumbDinosaur]

cjs wrote:

BigDumbDinosaur wrote:

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

[BigDumbDinosaur]

barrym95838 wrote:

BigDumbDinosaur wrote:

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

[barrym95838]

BigDumbDinosaur wrote:

Your comment reminds me of an old joke about understanding programming languages ...

https://www-users.york.ac.uk/~ss44/joke/foot.htm

[GARTHWILSON]

barrym95838 wrote:

BigDumbDinosaur wrote:

Your comment reminds me of an old joke about understanding programming languages ...

http://www.netzmafia.de/service/sprachen.html

LOL Then there's the "A Brief, Incomplete, and Mostly Wrong History of Programming Languages" which is quite humorous. One of the paragraphs:

Quote:

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.

[cjs]

BigDumbDinosaur wrote:

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.

Quote:

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.

Quote:

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.

[BillG]

cjs wrote:

Quote:

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

[load81]

BigDumbDinosaur wrote:

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.