[broken-kebab]

IMO the example shows exactly that splitting code in smaller pieces is way better than just commenting it.

It makes it easier for dev's brain to parse the code e.g. to understand what code really does, while fattier but commented version makes it harder but tries to replace it with information about original coder's intentions. Which is maybe important too but not as important as code itself.

Not to forget that it's too easy to change code and leave comments obsolete.

[BoorishBears]

Splitting example is way too much indirection, but capturing what the code does in the code itself is a preference for me. In any high level language don't know why the middleground wasn't explored:

    var hasSymbol = getSymbol(symbolName) != null
    var replacementPending = !alreadyReplaced.contains(symbolName)

    if(hasSymbol && replacementPending){
      alreadyReplaced.add(symbolName);
      stringToReplace = stringToReplace.replace("$" + symbolName, translate(symbolName));
    }

Technically this performs worse because you lose short-circuiting, but in performance-sensitive contexts code styling is less a concern anyways. And I also wouldn't rely on short-cutting alone to avoid a really expensive operation or side-effect: at some point someone will fail to notice it.

[1718627440]

As for the comments, I would probably write it like this:

    /* Symbol actually exists */
    if ((NULL != getSymbol (symbolName)
    /* and still to be added */
    &&  (!alreadyReplaced.contains (symbolName))
    {
        ...

Although in this specific case the comments seem like noise to me.

> Technically this performs worse because you lose short-circuiting

Not really, because optimizing compilers are a thing, when this thing is parsed into SSA, there won't be a difference.

[broken-kebab]

I like your version, and it's certainly possible to split too much without any practical result just for the dogma. But wrt the particular example I can see what's going on with a glance over the split part, while I have to focus at the commented one. Comments themselves can be helpful, but they can also be misleading cause code and coder's thoughts are not guaranteed to be in harmony all the time.

[zzo38computer]

I do not agree; I think the example that is not split is clearer and does not need comments to explain it (the variable names are helpful, although even if local variables use only one letter it still seems like clearly enough; for variables that are not local to that function, it does help to have a more descriptive names to understand them better). Comments and splitting can both be helpful in some circumstances, but neither is helpful for this one.