Hacker News Reader

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.

Xyz makes sense because that is what those axes are literally labeled, but ijk I will rail against until I die.

There's no context in those names to help you understand them, you have to look at the code surrounding it. And even the most well-intentioned, small loops with obvious context right next to it can over time grow and add additional index counters until your obvious little index counter is utterly opaque without reading a dozen extra lines to understand it.

(And i and j? Which look so similar at a glance? Never. Never!)

ijk are standard in linear algebra for vector components.

> (And i and j? Which look so similar at a glance? Never. Never!)

This I agree with.

What if not ijk? I know only uvw.

Pretend to be a physicist and use μ and ν.

i came from imaginary numbers which were extended to make quaternions.

i, j, k comes from FORTRAN's implicit types -- by default, names starting with I-N are integers and all other names are real.

this is much older ; Joseph Fourier was already using "i" and "j" for indices in the 1800s. See page 209: https://www.google.ca/books/edition/OEuvres_de_Fourier_Th%C3...

The context is i, j, k as indices in programs. No doubt FORTRAN was influenced by prior use such as you cite. But in no case does i used as an index come from i designating an imaginary number, which is what I aimed to refute.

Representing dimensions as indexable rows and columns of vectors or matrices was done on paper in the 1800s.

> but ijk I will rail against until I die.

> There's no context in those names to help you understand them, you have to look at the code surrounding it.

Hard disagree. Using "meaningful" index names is a distracting anti-pattern, for the vast majority of loops. The index is a meaningless structural reference -- the standard names allow the programmer to (correctly) gloss over it. To bring the point home, such loops could often (in theory, if not in practice, depending on the language) be rewritten as maps, where the index reference vanishes altogether.

I respectfully disagree.

The issue isn't the names themselves, it's the locality of information. In a 3-deep nested loop, i, j, k forces the reader to maintain a mental stack trace of the entire block. If I have to scroll up to the for clause to remember which dimension k refers to, the abstraction has failed.

Meaningful names like row, col, cell transform structural boilerplate into self-documenting logic. ijk may be standard in math-heavy code, but in most production code bases, optimizing for a 'low-context' reader is not an anti-pattern.

If the loop is so big it's scrollable, sure use row, col, etc.

That was my "vast majority" qualifier.

For most short or medium sized loops, though, renaming "i" to something "meaningful" can harm readability. And I don't buy the defensive programming argument that you should do it anyway because the loop "might grow bigger someday". If it does, you can consider updating the names then. It's not hard -- they're hyper local variables.

In a single-level loop, i is just an offset. I agree that depending on the context (maybe even for the vast majority of for loops like you're suggesting) it's probably fine.

But once you nest three deep (as in the example that kicked off this thread), you're defining a coordinate space. Even in a 10-line block, i, j, k forces the reader to manually map those letters back to their axes. If I see grid[j][i][k], is that a bug or a deliberate transposition? I shouldn't have to look at the for clause to find out.

If you see grid[y][z][x], is it a bug or a deliberate transposition?

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

You seem to be missing my point. It's not about improving "clarity" about the math each line is doing -- that's precisely the kind of misconception so many people have about comments.

It's about, how long does it take me to understand the purpose of a block of code? If there was a simple comment at the top that said [1]:

  # Calculate top-left point of the bounding box

then it would actually be helpful. You'd understand the purpose, and understand it immediately. You wouldn't have to decode the code -- you'd just read the brief remark and move on. That's what literate programming is about, in spirit -- writing code to be easily read at levels of the hierarchy. And very specifically not having to read every single line to figure out what it's doing.

The original assertion that "This code is so literate, so easy to read" is demonstrably false. Naming something "pt" is the antithesis of literature programming. And if you insist on no comments, you'd at least need to name is something like "bbox_top_left". A generic variable name like "pt", that isn't even introduced in the context of a loop or anything, is a cardinal sin here.

[1] https://news.ycombinator.com/item?id=46366341

It all depends on how much context the reader has. For some audiences a comment explaining bounding boxes would be helpful; for others your example comment adds nothing that isn't immediately apparent from the code.

Part of figuring out a reasonable level of commenting (and even variable naming) is a solid understanding of your audience. When in doubt aiming low is good practice, but keep in mind that this was 2D graphics software written at a 2D graphics software company.

I think at certain calibers of work, like graphics programming in lower level languages, the best you can do is be readable and clear to others who are experts in your field. In other words, you aren't the target audience. There is likely no way to write this specific kind of code in a way that satisfies all audiences. I'm willing to concede then that the 'best' way to write this type of code is determined by the ones writing it, not us with standard views on software.

A graphics programmer does not need that.

To help understand, you need to see this code as math. Graphics programming algorithms are literally math.

You're asking for training wheels comments, which just get in the way for those who are familiar with the domain.

I'm sure a few graphics programming engineers might want calls to react useState(), useEffect(), etc. to be documented in a codebase, yet a react programmer would scoff at the idea.

Exactly this.

To a graphics programmer this can feel like call for comments to explain that

i++

increments the loop variable. A newbie to programming might find such a comment useful, but to people who are maintaining such a piece of code that would be distracting line noise.

It all depends on who your professional peer is that you are writing the code for. It's totally fine to write for a peer who is familiar with the domain, as it's fine to write for a beginner, for pedagogy, such as in a text book.

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%);


}

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

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.

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

Reading the full function here https://github.com/amix/photoshop/blob/2baca147594d01cf9d17d...

If I understand it correctly, it was calculating the top-left point of the bounding box.

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

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

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.

>> Every comment is a line of code, and every line of code is a liability, and, worse, comments are a liability waiting to rot,

This is exactly my view. Comments, while can be helpful, can also interrupt the reading of the code. Also are not verified by the compiler; curious, in the era when everyone goes crazy for rust safety, there is nothing unsafer as comments, because are completely ignored.

I do bot oppose to comments. But they should be used only when needed.

No. What you are describing is exactly the myth that needs to die.

> comments are a liability waiting to rot, to be missed in a refactor, and waiting to become a source of confusion

This gets endlessly repeated, but it's just defending laziness. It's your job to update comments as you update code. Indeed, they're the first thing you should update. If you're letting comments "rot", then you're a bad programmer. Full stop. I hate to be harsh, but that's the reality. People who defend no comments are just saying, "I can't be bothered to make this code easier for others to understand and use". It's egotistical and selfish. The solution for confusing comments isn't no comments -- it's good comments. Do your job. Write code that others can read and maintain. And when you update code, start with the comments. It's just professionalism, pure and simple.

For all we know, the comment came from someone who was doing their job (by your definition) and were bitten in the behind by colleagues who did not do their job. We do not live in an ideal world. Some people are sloppy because they don't know, don't care, or simply don't have the time to do it properly. One cannot put their full faith into comments because of that.

(Please note: I'm not arguing against comments. I'm simply arguing that trusting comments is problematic. It is understandable why some people would prefer to have clearly written code over clearly commented code.)

> colleagues who did not do their job.

That doesn't justify matching their sloth.

Lead by example! Write comments half a page long or longer, explaining things, not just expanding identifier names by adding spaces in between the words.

I have mixed feelings on this. In most respects, I am a diligent worker who tries to lead by example. On the other hand, part of my work is managing people. While I have employees who follow my example, even when I am not intending my habits to be an example, and I adore those employees immensely -- I also have to face the reality that very few employees do so. They need direction on what is expected. Even then, the direction has to take the form of intense instruction otherwise ... woosh ... the details go over their heads.

That, and I have mixed feelings about commenting code. (Thankfully I don't managed developers. I simply exploit personally since it a skill that I have.) I understand why we do it. I especially appreciate well documented libraries and development tools. On the other hand, I fully understand that comments only work if they are written, read, and updated. The order is important here since documentation will only be updated if it is read and it will only be read if it is (well) written. Even then you are lucky if well written documentation is read.

The flip side is that comments are duplication. Duplication is fine if they are consistent with each other. In some respects, duplication is better since it offers multiple avenues for understanding. Yet there is also a high probability that they will get out of sync. Sometimes it is "intentional" (e.g. someone isn't doing their job by updating it). Sometimes it is "unintentional", since the interpretation of human languages is not as precise as the compiler's translation of source code into object code. (Which is a convoluted way of saying that sometimes comments are misinterpreted.)

Generally, high standards can only be achieved through enforcement, not merely through begging and pleading.

I like to add myself as a mandatory reviewer of all PRs and then reject changes that don't come with some explanatory comment or fail to update comments.

Even if huge swaths of the codebase are undocumented boring boilerplate, you still have to draw the line somewhere, otherwise you get madness like ten pages of authentication and authorization spaghetti logic without a single descriptive comment.

I appreciate your attempt to defend this position and I, and others, wish you good luck. In my many decades of working with humans writing code it simply has never happened.

It definitely happens.

I've worked at places (early on) that were basically cowboy coding -- zero code review, global variables everywhere, not a comment or test to be seen. Obviously you can't enforce good comments there.

And I've worked at places that were 100% professional -- design documents, full code review, proper design, tests, full comments and comments kept fully up-to-date just like code.

It's just the culture and professionalism. If proper comments are enforced through code review, they happen. Ultimately, the head of engineering just decides whether it's part of policy or not. It's not hard. It's just a top-down decision.

No amount of good names will tell you why something was done a certain way, or just as importantly why it wasn't done a certain way.

A name and signature is often not sufficient to describe what a function does, including any assumptions it makes about the inputs or guarantees it makes about the outputs.

That isn't to say that it isn't necessary to have good names, but that isn't enough. You need good comments too.

And if you say that all of that information should be in your names, you end up with very unwieldy names, that will bitrot even worse than comments, because instead of updating a single comment, you now have to update every usage of the variable or function.