Don't use `ds $150 - @, 0` so early in the tutorial

[Rangi42]

Section I.6, "Assembly basics", is going over the first few lines in hello-world.asm. It explains the concepts of "comments", "instructions", "directives", and "sections", which are all fundamental and important and widely used, all unavoidable complexity at this point. However, I think ds $150 - @, 0 is overly complicated this early on.

Using the words "simply" and "simple" twice in explaining one line is probably a sign that it's not simple. The ds directive is not very useful outside of this particular context, and the @ symbol is also a pretty advanced concept, especially given the details of what its value is when used with instructions (it depends on the instruction size).

Given that the section is at a fixed address, the header is of a fixed size, the jp EntryPoint instruction is not going to change, and no code is going to be added here besides that one jp, I think it would be acceptable to hard-code the size of $4D here.

• We could keep using ds, with size $4D or $150 - $100 - 3, 0. Either way we would need to explain in the subsequent paragraph that since the section is at address $100, we want to get to address $150, and the jp instruction takes up three bytes, then we need to skip $150 - $100 - 3 = $4D bytes. The choice is whether to show that calculation in the code (maybe it's more clear that way, but maybe it just looks noisy/intimidating).

• Or, we could introduce the rept directive instead of ds (it's more broadly useful later on, for repeating code or data). That would also allow us to use the nop instruction instead of db 0, since "instructions" are an already-introduced concept. The repetition count could again be $4D or $150 - $100 - 3.

The main reason I can think of to keep ds $150 - @, 0 is that it's idiomatic in well-written code by an experienced dev. However, if that's the reasoning we're going with, I see a lot of lower-hanging fruit to tackle before introducing @ -- like the jr instruction, .local labels, calling subroutines, INCBINning data... all applicable to this Hello World example, and all more relevant to larger projects than @ is.

[ISSOtm]

Good points! I would rather have a single ds (I think it's too early to introduce the macro language), but am not entirely sure what argument to use. ds $4D is simplest (doesn't feel arcane like ds $150 - $103 would), and since we're cargo-culting that line (deferring its explanation to later), might as well go all the way.

Thus, my vote goes to ds $4D.

[quinnyo]

I think there's some value in teaching @ (other than the value in teaching the thing itself). I don't expect it to be particularly useful directly, practically to someone at that point in the tutorial, but:

• it reinforces understanding of the whole assembly thing
  • how the code maps so tightly to the generated binary, I mean
  • this is one of the things that make an assembly language an assembly language and its something that people (even those with high level programming experience) can struggle with
• it's a relatively easy, small, thing to learn about that is actually a doorway into learning about macros

Kill simply.

I agree that teaching ds isn't a high priority, but it seems fairly harmless.

This is a tiny fragment of code that's reasonably safe to use without understanding it, so it's pretty easy for a reader that doesn't understand the details to move forward anyway. This is not a call to avoid making changes. If you can skip it, some will. Just something to consider.

Of the options presented, using ds with a single constant length is clearly the easiest one to make sense of ("it fills this many bytes" is essentially the entire explanation).

• using an expression with only literal constant operands seems needlessly complicated.
• changing to rept or similar seems like a sideways step at best, you're left with the same problem.
  • at worst, you're then explaining macros/~metaprogramming instead which is a topic that tends to overwhelm
    • obviously this is a good thing to teach people about, I'm just saying that it's a can of worms at this specific point
    • @ would be a good first step in learning about macros.

Any valid argument for removing this from early in the tutorial seems valid for later as well. It's not important to use this particular construct.

[ISSOtm]

Assuming the “build then refine” scheme from #156 is adopted, then we could start with ds $4D in Part I, and turn it into ds $150 - @ in Part II?

[Rangi42]

Closing this, any such changes may as well be discussed in #156.