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!

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

_________________
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)

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.


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

_________________
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?

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.

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

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

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!

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)

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!

It's too bad we don't have sarcasm tags here.

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

_________________
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)

_________________
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?

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.


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:


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

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.

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.