Comment by ofrzeta

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.

As other comments have mentioned, context does matter, and as someone with a lot of 2D image/pixel processing experience, other than the 'BSR' and 'ORD4' items - which are clearly common in the codebase and in that era of computing, all that code makes perfect sense.

Also, breaking things down to more atomic functions wasn't the best idea for performance-sensitive things in those days, as compilers were not as good about knowing when to inline and not: compiler capabilities are a lot better today than they were 35 years ago...

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;
    }

Are you familiar with the domain?

Because it's quite clear, everything is well named, and the filename also gives the context.

Finds the center of a rectangle r Positions a width × height region centered on that rectangle.

Clamps the result so it doesn’t go outside the document.

If the region is bigger than the document, it re-centers instead of snapping to (0,0).

The code's functionality is immediately obvious to me as someone who works a lot with graphics coordinate systems.

I'm sure the code would be immediately obvious to anyone who would be working on it at the time.

Comments aren't unnecessary, they can be very helpful, but they also come with a high maintenance cost that should be considered when using them. They are a long-term maintenance liability because by design the compiler ignores them so its very easy to change/refactor code and miss changing a comment and then having the comment be misleading or just plain wrong.

These days one could make some sort of case (though I wouldn't entirely buy it, yet) that an LLM-based linter could be used to make sure comments do not get disconnected from the code they are documenting, but in 1990? not so much.

Would I have used longer variable names for slightly more clarity? Today, sure. In 1990, probably not. Temporal context is important and compilers/editors/etc have come a long way since then.

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.