Cognitive load is what matters

(github.com)

Show context

Buttons840 ◴[30 Aug 25 14:42 UTC] No.45075079[source]▶

It's been said: "Document the why, not the what."

I have a hard time separating the why and the what so I document both.

The biggest offender of "documenting the what" is:

    x = 4  // assign 4 to x

Yeah, don't do that. Don't mix a lot of comments into the code. It makes it ugly to read, and the context switching between code and comments is hard.

Instead do something like:

    // I'm going to do
    // a thing. The code
    // does the thing.
    // We need to do the
    // thing, because the
    // business needs a
    // widget and stuff.
    
    setup();
    t = setupThing();
    t.useThing(42);
    t.theWidget(need=true);
    t.alsoOtherStuff();
    etc();
    etc();

Keep the code and comments separate, but stating the what is better than no comments at all, and it does help reduce cognitive load.

replies(6): >>45075259 #>>45075314 #>>45075395 #>>45076149 #>>45079235 #>>45080058 #

marginalia_nu ◴[30 Aug 25 15:02 UTC] No.45075259[source]▶

>>45075079 #

I generally don't mind documenting both when it's merited. Sometimes you need to clarify the why, occasionally you need to clarify the what.

I think comments in general are underrated. You don't need to annotate every line like a freshman programming assignment, but on the other hand most supposed self-documenting code just isn't.

replies(1): >>45075299 #

1. mastermage ◴[30 Aug 25 15:06 UTC] No.45075299[source]▶

>>45075259 #

sometimes you do some wack magic in just one line of code, sometimes thats necessary for performance or because what you are trying todo is inherently wack magic. Example the fast inverse square from quake. Insane magic and if you just document does inverse square approximately people would freak out. So sometimes when wack magic is used explain the wack magic (as concise as reasonable)

replies(1): >>45075386 #

2. marginalia_nu ◴[30 Aug 25 15:18 UTC] No.45075386[source]▶

>>45075299 (TP) #

Yup.

I've got a function the gist of which is

  if (!cond())
    return val;

  do {
    // logic
  } while (cond());

  return val;

This looks like it could be simplified as

  while (cond())
    // logic
  }
  return val;

But if you do you lose out on 20% of performance due to branch mispredictions, and this is a very hot function. It looks like a mistake, like the two are equivalent, but they are actually not. So it gets a comment that explains what's happening.

replies(1): >>45075647 #

3. brokencode ◴[30 Aug 25 15:50 UTC] No.45075647[source]▶

>>45075386 #

That feels like.. something the compiler should be optimizing for you? I would certainly be among those questioning this code.

replies(1): >>45075671 #

4. marginalia_nu ◴[30 Aug 25 15:54 UTC] No.45075671{3}[source]▶

>>45075647 #

The compiler can't know from the code alone which branch is more likely. This is a property of the input data and not the code. Really advanced JIT compilers can sometimes do those types of optimizations, but this is a fairly rare scenario.

replies(2): >>45076830 #>>45076966 #

5. jijijijij ◴[30 Aug 25 18:13 UTC] No.45076830{4}[source]▶

>>45075671 #

Isn't branch prediction mostly a CPU thing? Do you have an example with corresponding assembly?

It's not that I don't believe you about the performance impact, as I have observed the same with e.g. Rust in some cases, but I don't think it has a lot to do with the compiler judging what's more likely, but rather more or less "random" optimization differences/bugs. At least in my case, the ordering had nothing to do with likelihood, or even had a reverse correlation.

I think in your example a compiler may or may not realize the code is semantically equivalent and all bets are off about what's going to happen optimization-wise.

I mean, in the end it doesn't matter for the commenting issue, as you are realistically not going to fix the compiler to have slightly more readable code.

replies(1): >>45076924 #

6. marginalia_nu ◴[30 Aug 25 18:28 UTC] No.45076924{5}[source]▶

>>45076830 #

I don't have an assembly output for this particular case, but how I understand it is that the re-write basically turns it into two separate conditions, which means the branch predictor is free to model their outcomes separately.

In this case, the data is bimodal, depending on the chosen input, two likely outcomes exists. Either no looping is needed, or much looping is needed. This seemingly confuses the branch predictor when it's the same branch dealing with both scenarios.

7. whitehexagon ◴[30 Aug 25 18:35 UTC] No.45076966{4}[source]▶

>>45075671 #

The other day I spotted Zig has @branchHint, not tried it yet, my code isnt that hot!

↑