Cognitive load is what matters

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.

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.

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)

I am trying to shift more to this style of commenting. Because I am not a programmer by education. I am a physicist and most physicists are like I want comments in my code so do it like this.. and then you as a student do what you need to for a good grade.

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.

> x = 4 // assign 4 to x

Ah, the chat gpt style of comments.

> Instead do something like:

The only negative is that there is a chance the comment becomes stale and not in sync with the code. Other coders should be careful to update the comment if they touch the code.

If the what becomes stale, you can tell. If the why becomes stale (and it can become stale), you'll never know, unless the what is also included.

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

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.

The reason you want people to document the "why" is because you can easily check if one reason has become stale, but you can never check if every single possible reason is still valid.

The challenge I have these days is deciding what belongs in code and what goes into design documentation and technical manuals.

I generally find that comments in code should explain why the code is doing non-obvious things. “This gets memoized because it’s actually important to maintain referential identity for reason X.”

The why becoming stale is a feature, that's when you know there is a VALID reason you thought this looked weird and convoluted, instead of you completely missing the inherent complexity of the problem.

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.

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.

The problem is, a year later the obvious things are not obvious anymore :D

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

Such comments are never maintained. Implementation will change 5 times this year and the comment will get stale and confusing.

At my current projects we drop all code comments except for some really tricky logic and very high level docs.

> It makes it ugly to read, and the context switching between code and comments is hard.

That's a symptom of bad syntax highlighting, fix it and you're good to go.