That particular code is idiomatic to anyone who worked with 2D bitmap graphics in that era.

pt == point, r == rect, h, v == horizontal, vertical, BSR(...,1) is a fast integer divide by 2, ORD4 promotes an expression to an unsigned 4 byte integer

The algorithms are extremely common for 2D graphics programming. The first is to find the center of a 2D rectangle, the second offsets a point by half the size, the third clips a point to be in the range of a rectangle, and so on.

Converting the idiomatic math into non-idiomatic words would not be an improvement in clarity in this case.

(Mac Pascal didn't have macros or inline expressions, so inline expressions like this were the way to go for performance.)

It's like using i,j,k for loop indexes, or x,y,z for graphics axis.

This actually looks surprisingly straightforward for what the function is doing - certainly if you have domain context of image editing or document placement. You'll find it in a lot of UI code - this one uses bit shifts for efficiency but what it's doing is pretty straightforward.

For clarity and to demonstrate, this is basically what this function is doing, but in css:

.container {

  position: relative;

.obj {

  position: absolute;

  left: 50%;

  top: 50%;

  transform: translate(-50%, -50%);


}

BSR = bitwise right-shift

ORD4 = cast as 32bit integer.

BSR(x,1) simply meant x divided by 2. This is very comment coding idom back in those days when Compiler don't do any optimization and bitwise-shift is much faster than division.

The snippet in C would be:

    pt.h = (r.left + (int32_t)r.right) / 2;
    pt.v = (r.top + (int32_t)r.bottom) / 2;

    pt.h -= (width / 2);
    pt.v -= (height / 2);
  
    pt.h = max(0, min(pt.h, fDoc.fCols - width));
    pt.v = max(0, min(pt.v, fDoc.fRows - height));
  
    if (width > fDoc.fCols) {
      pt.h -= (width - fDoc.fCols - 1) / 2;
    }
  
    if (height > fDoc.fRows) {
      pt.v -= (height - fDoc.fRows - 1) / 2;
    }

It’s not a myth, it’s a sound software engineering principle.

Every comment is a line of code, and every line of code is a liability, and, worse, comments are a liability waiting to rot, to be missed in a refactor, and waiting to become a source of confusion. It’s an excuse to name things poorly, because “good comment.” The purpose of variables should be in their name, including units if it’s a measurement. Parameters and return values should only be documented when not obvious from the name or type—for example, if you’re returning something like a generic Pair, especially if left and right have the same type. We’d been living with decades of autocomplete, you don’t need to make variables be short to type.

The problem with AI-generated code is that the myth that good code is thoroughly commented code is so pervasive, that the default output mode for generated code is to comment every darn line it generates. After all, in software education, they don’t deduct points for needless comments, and students think their code is now better w/ the comments, because they almost never teach writing good code. Usually you get kudos for extensive comments. And then you throw away your work. Computer science field is littered with math-formula-influenced space-saving one or two letter identifiers, barely with any recognizable semantic meaning.

Man I just don’t know who to believe, you or the Chief Scientist for Software Engineering at IBM research Almaden.