> Let the subroutine itself do the returning for us. You save one byte
> (whoooooo!) but also you gain 8 cycles - 6 as you're not doing the redundant
> rts, and 2 because you're jumping instead of jsring. The general principle:
> wherever you see a jsr followed immediately by a rts, you can replace the
> pair with a jmp, AND AN EXPLANATORY COMMENT OF WHAT THE HELL YOU'VE DONE!!!!
I think that last line was the most important part of the whole message.
The jsr/rts to jmp thing is something I've done many times before, but
only because I used something similar programming BASIC: replacing a
GOSUB and RETURN with a GOTO. And I pulled all kinds of shenanigans
in BASIC in search of optimization. Then at a certain point my code
became too messy to maintain and I just abandoned it. I'd never think
of using a REM statement; the possibility that it could slow down the
program was too great. And so my programs became very obfuscated; upon
returning to a program after a week or so, I'd spend half an hour trying
to remember how I implemented something before I could figure out why
it didn't work a week ago.
Remember, even if you're not going to release the source code, you'll
want to be able to understand it with relative ease, in case you have
to leave it alone for a little while.
It might also be wise to put a comment after your RTS stating which
subroutine you're returning from. And after every TAX, state what
you just transferred to X, and what it would be used for later.
And, of course, if you're performing a strange algorithm with lots
of bit shifts and OR's and such, explain what you're doing. Are
you doing that ROR to divide by two, or are you playing with the
carry bit? And something I've done lately is to make sure my
branches have a comment in them describing what it would look like
as an "IF" statement, either in a high-level language or in English.
This sort of thing was very prevalent in my 640x200-scroll routine
I whipped up for the Commodore 64; I'm eventually going to submit
an article about it to C=Hacking, since it's already been in a few
demos.
In general, if you have to ask whether you need to use a comment,
use a comment. It's always easier to get rid of extraneous comments
than it is to reverse-engineer yourself.
If you're wondering whete I picked up this habit, I learned it in,
of all places, my COBOL class. COBOL is very English-like for the
most part, with statements like "MULTIPLY CORRECT-ANSWERS BY 6"
and "IF TREAD-MARKS IS LESS THAN DESSERT-TOPPINGS" and other
sentence-like things. Even when the code doesn't resemble sentences,
it is still made up of more words than symbols. You can even put
hyphens in your variable names, so you don't have to create
NamesLikeThis or use_ugly_underscores or B2BRIEF. But since not
all programmers like to be this verbose, a lot of things are
optional. And I include a lot of optional things. I always declare
arrays using "OCCURS 12 TIMES" rather than "OCCURS 12" because it
parses better. It's as if I'm programming in prose, and I want to
add color to what I do. And the proliferation of actual words
make commenting easier, from an aesthetic standpoint.
I noticed a sort of disparity between the code posted to this page,
as I look through Garon's source code archive here...
Chris Cracknell's color display program isn't the best example of
compact 6502 code; with a BNE right next to a JMP and that sort of
thing. But he makes sure to put comments on every block of code,
perhaps because in his own inexperience he might forget the purpose
of his own code. I expected this of a beginning program, but the
tradition continued up into his clock program, where each block of
code has, at the very least, a heading comment that describes the
block of code. The variables are also described with comments.
I've noticed a lot of source listings, though, which have large
blocks of code without a single comment. Sometimes there aren't
even labels assigned to RAM locations. There is only the occasional
cycle count, usually, and a disturbing trend I'm seeing is that
the most obvious code sections are commented line-by-line, such as
the vertical blank, while the most obscure parts are left undocumented.
This approach draws the reader's attention away from the most unique
parts of the program, which is most undesirable when one is trying
to introduce the list to a new trick. It would be preferable to
put brief headers in front of such code and explain them away, and
put more effort into the meat of the program.
I'd like to suggest a few guidelines at this point. The vertical
blank, for example, needs little more than a header line and perhaps
a comment near the TIM64T setting, pointing out how many scanlines
it's setting for. Anything else is probably not needed. A new
trick or technique, on the other hand, should ALWAYS include enough
information to allow other programmers to put it in their programs.
The bare minimum would be to describe the parameters and variables,
i.e. "FOO_1 is the size of the sprite, and can be 3, 7, 15, 31, or
63" and the like. If it's used in a kernel, the comment should
tell you how many cycles you have left for instructions, and where
you may safely put them. If the code is flexible, there should be
comments on how one can change the code. And if the code is just
too magical to talk about, don't worry about being specific. Just
ask yourself what the programmer needs to know.
Remember, editing that Combat listing took me a long time, and there
is a lot that I have yet to figure out on my own. 6502 programming
is a very tricky business, and nobody can guarantee that the code
will speak for itself.
</SOAPBOX>
--
Archives (includes files) at http://www.biglist.com/lists/stella/archives/
Unsub & more at http://www.biglist.com/lists/stella/stella.html
