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.

> 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.