[COFF] Code/comment Ratios Style

[segaloco via COFF]

On Monday, July 21st, 2025 at 3:27 PM, josh <joshnatis0 at gmail.com> wrote:

> On Monday, July 21, 2025, Chet Ramey via COFF <coff at tuhs.org> wrote:
> 
> > On 7/21/25 11:27 AM, Paul Winalski wrote:
> > 
> > > 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.
> 
> 
> 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...

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.