21 Jul
2025
21 Jul
'25
10:44 p.m.
On Monday, July 21st, 2025 at 3:27 PM, josh <joshnatis0(a)gmail.com> wrote:
On Monday, July 21, 2025, Chet Ramey via COFF
<coff(a)tuhs.org> wrote:
Something I've taken to in disassembly analysis that has then crept into my assembly
coding as well is placing C-like flow control/conditional operations in comments and using
indentation to denote loops and such. For instance (the naked : and :- in ca65 syntax are
like cheap local labels e.g. 1: and 1b in AT&T-like assemblers):
ldx #(player_lives_b-player_lives)-1
: ; for (value of per_player_values) {
lda player_lives, x
pha
lda player_lives_b, x
sta player_lives, x
pla
sta player_lives_b, x
dex
bpl :-
; }
This is a loop that swaps player stats when switching from player 1 to player 2 in Super
Mario Bros. (6502 assembly) and here I've used indentation and a for-of loop (not C,
JavaScript, but still visually comparable) so that way it's a little more obvious on
first inspection this is a loop over the per-player-values array for each member. Granted
it is literally just commentary, but I can't tell you how many times this sort of
thing has helped me narrow down exactly where something is happening. I've also
found it nice in some graphical editors as they'll automatically offer to "roll
up" code between two semicolons from other languages, so I can similarly shutter bits
of an assembly file based on how deeply nested in the control flow they are, ignoring
loops/conditions I don't care about when reading through something. Also when
writing my own code, it sometimes helps me ensure I'm keeping things relatively
sensible, I've more than once rewritten something to be clearer when I tried to wrap
it in comments like this and just couldn't make heads or tails of the segregation of
the different conditions.
Of course, the final code is the assembly, not the commentary, so it's important to
recognize that. I prefer it to the no-indentation and comments on every line approach I
see in some assembly stuff. Of course ymmv depending on the assembler in use, but this
has been quite helpful in my 6502 stuff with the cc65 suite.
- Matt G.
On 7/21/25 11:27 AM, Paul Winalski wrote:
Does anyone else feel like this is still an unsolved problem?
It seems git blame continues to be the state of the art for connecting a section of code
to the “commit” (or analogous concept) in which it was added, which is where one would
include context about why the change was made and connect it to the wider world (bug
tracker, etc).
There is a lot to say about a change which would be extraneous to include in the code as
comments — real-world context (as mentioned), trade-offs considered / why specific
implementation decisions were made, explanation and annotation, potential future steps,
testing/validation, and even rich media demonstrating things that may be hard to express
in text.[1]
This all goes in the “pull request” UI on GitHub, or the email thread discussing a patch.
Now why does all this only have a tenuous connection to the actual code once it’s merged?
Any little nudge will override the git blame. Shouldn’t there be a more formal connection
between the code and its history? (Not to mention one doesn’t always think to check the
history when reading code, that only becomes necessary when something isn’t clear. Let’s
be honest, how often do we go out of our way to do this?).
Maybe this is a fundamental trade-off of code being plain text rather than being stored
as some rich/structured representation.
Now that I wrote this all out, I’m starting to feel like I’ve heard flame wars about git
blame before, so I’m sorry if I ended up beating a dead horse on accident :-P.
Josh
[1] I can see how having an outlet for all these things can remove incentives to make the
code itself understandable without external reference, which is pretty problematic...
When writing all but the most trivial bug fixes I
always put in a comment referring to the bug report number. This helps with what can
otherwise be a perplexing problem: "why is this bit of code there?"
I put those in the change log entries.