6502.org Forum  Projects  Code  Documents  Tools  Forum
It is currently Sat Nov 09, 2024 10:59 pm

All times are UTC




Post new topic Reply to topic  [ 48 posts ]  Go to page Previous  1, 2, 3, 4  Next
Author Message
PostPosted: Fri May 01, 2020 4:22 am 
Offline
User avatar

Joined: Thu May 28, 2009 9:46 pm
Posts: 8479
Location: Midwestern USA
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:
;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.

_________________
x86?  We ain't got no x86.  We don't NEED no stinking x86!


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 5:10 am 
Offline
User avatar

Joined: Sun Jun 30, 2013 10:26 pm
Posts: 1948
Location: Sacramento, CA, USA
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:
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

_________________
Got a kilobyte lying fallow in your 65xx's memory map? Sprinkle some VTL02C on it and see how it grows on you!

Mike B. (about me) (learning how to github)


Last edited by barrym95838 on Fri May 01, 2020 5:38 am, edited 1 time in total.

Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 5:20 am 
Offline
User avatar

Joined: Sat Dec 01, 2018 1:53 pm
Posts: 727
Location: Tokyo, Japan
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.

_________________
Curt J. Sampson - github.com/0cjs


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 6:21 am 
Offline
User avatar

Joined: Fri Aug 30, 2002 1:09 am
Posts: 8538
Location: Southern California
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.

_________________
http://WilsonMinesCo.com/ lots of 6502 resources
The "second front page" is http://wilsonminesco.com/links.html .
What's an additional VIA among friends, anyhow?


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 6:53 am 
Offline
User avatar

Joined: Thu May 28, 2009 9:46 pm
Posts: 8479
Location: Midwestern USA
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? :lol: 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.

_________________
x86?  We ain't got no x86.  We don't NEED no stinking x86!


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 7:03 am 
Offline
User avatar

Joined: Sat Dec 01, 2018 1:53 pm
Posts: 727
Location: Tokyo, Japan
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.

_________________
Curt J. Sampson - github.com/0cjs


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 7:05 am 
Offline
User avatar

Joined: Thu May 28, 2009 9:46 pm
Posts: 8479
Location: Midwestern USA
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.

_________________
x86?  We ain't got no x86.  We don't NEED no stinking x86!


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 7:14 am 
Offline
User avatar

Joined: Sun Jun 30, 2013 10:26 pm
Posts: 1948
Location: Sacramento, CA, USA
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! :)

_________________
Got a kilobyte lying fallow in your 65xx's memory map? Sprinkle some VTL02C on it and see how it grows on you!

Mike B. (about me) (learning how to github)


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 7:24 am 
Offline
User avatar

Joined: Thu May 28, 2009 9:46 pm
Posts: 8479
Location: Midwestern USA
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.

_________________
x86?  We ain't got no x86.  We don't NEED no stinking x86!


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 7:25 am 
Offline
User avatar

Joined: Thu May 28, 2009 9:46 pm
Posts: 8479
Location: Midwestern USA
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. :D

_________________
x86?  We ain't got no x86.  We don't NEED no stinking x86!


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 7:44 am 
Offline
User avatar

Joined: Sun Jun 30, 2013 10:26 pm
Posts: 1948
Location: Sacramento, CA, USA
BigDumbDinosaur wrote:
Your comment reminds me of an old joke about understanding programming languages ...

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

_________________
Got a kilobyte lying fallow in your 65xx's memory map? Sprinkle some VTL02C on it and see how it grows on you!

Mike B. (about me) (learning how to github)


Last edited by barrym95838 on Mon Aug 14, 2023 7:29 am, edited 1 time in total.

Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 8:20 am 
Offline
User avatar

Joined: Fri Aug 30, 2002 1:09 am
Posts: 8538
Location: Southern California
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.

_________________
http://WilsonMinesCo.com/ lots of 6502 resources
The "second front page" is http://wilsonminesco.com/links.html .
What's an additional VIA among friends, anyhow?


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 10:58 am 
Offline
User avatar

Joined: Sat Dec 01, 2018 1:53 pm
Posts: 727
Location: Tokyo, Japan
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:
    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.

_________________
Curt J. Sampson - github.com/0cjs


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 12:46 pm 
Offline

Joined: Thu Mar 12, 2020 10:04 pm
Posts: 704
Location: North Tejas
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:
 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


Top
 Profile  
Reply with quote  
PostPosted: Fri May 01, 2020 2:27 pm 
Offline

Joined: Fri Nov 16, 2018 8:55 pm
Posts: 71
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.


Top
 Profile  
Reply with quote  
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 48 posts ]  Go to page Previous  1, 2, 3, 4  Next

All times are UTC


Who is online

Users browsing this forum: No registered users and 4 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to: