Felienne Hermans: How patterns in variable names can make code easier to read

Let's say you have some non-trivial class that includes, among others, some 2d rectangular data: An x, y, width, and height. They're all related, but they don't naturallly occur near each other without a little massaging:

coordX, coordY, sizeWidth, sizeHeight?

xMin, xMax, yMin, yMax?

coordXMin, coordXMax, coordYMin, coordYMax?

I generally agree with your sentiment, but there's a reason "naming things" is one of the hardest problems in computer science :)

IMO a big alphabetical list of everything in your project is not a useful or important thing. Use a language that has good support for hierachical namespaces, and use them.

It's the difference between taking, say, 2 seconds to read a method, and 10 or more.

I can only assume people who don't treat code formatting as a rule read every.single.thing.line.by.line.every.time.

As far as 'consistent' names go, there are multiple dimensions of sameness. Using the same word for all instances of the same concept, not using the same word for other concepts, using consistent pluralization. Using same adjective/adverb/gerund form for related concepts. You are telegraphing sameness in these cases, and difference in others.

We have tried things similar to what you describe before, we just have dialed it in wrong. New-ish, good ideas often fall prey to bad execution. Hungarian notation, for instance, dictates that the variable name stays the same when the sense of the data changes, but is supposed to change when the implementation details shift. Which is exactly the opposite of what we want. If I fix a Y2K bug or a 2038 bug in due_on, I'm going to end up with a slightly different structure, but the deadline it represents is still 12 midnight. And if it's not, well, maybe we need a different convention for calendar day versus business day deadlines.

The "big-endian naming mould" suggests naming it orders_per_month_max, since orders is the object (most significant), per_month is a count of orders (secondary significance), and max is a constraint of the order per month count (least significant).

Then you can use other parallel names in the same big-endian pattern, like orders_per_month orders_per_year orders_per_year_max orders_per_second_min refunds_per_year_average etc, and they will all sort next to their closely related names, instead of the "inline max" or "prefix max" scrambling the alphabetical order.

I once worked in a place in the 1990s that took it to such an extreme that every table name, column name, and variable name had to be approved by a naming standards committee before it could go into production. IIRC the committee met once a month, maybe twice? Which was not ideal for the developers but changes only went to production once a month during a "change window" anyway.

Naming conventions can help with code readability, but don't let the process become more important than the goals.

               Wide Scope     Narrow Scope
             +-------------+-------------
    Function | Short Name  |  Long Name
             +-------------+-------------
    Variable | Long Name   |  Short Name
             +-------------+-------------

    I can’t quite explain why this works

The general principle uniting all 4 quadrants of the table is: "Use names just long enough to be clear, but not longer."

Here's an illuminating exception to the heuristics: The use of the very short global "DB" for database.

We are really trying to balance two competing goals:

1. Brevity -- Don't explain what I already know. You mention this in relation to a tight loop variable: "I bet you didn’t need me to explain dL stood for Drivers License. It might have even annoyed you if I had spelled it out."

2. Clarity -- Don't confuse me. Don't make me look something up to figure it out.

Maximize brevity while retaining clarity.

Clarity is related to frequency of use. This relates to your comment: "How come the jQuery constructor feels much more natural than the native version? document.querySelectorAll('#appContainer')". It is annoying because we use it all the time... we don't need or want a verbose description.

If the thing is used everywhere, and especially if it is a general convention, assume familiarity. Sure, someone might be confused by "DB" the first time they ever see it, but it will quickly become part of their lexicon and remain so through repeated exposure. However, the same cannot be said for "CGTAO" as a stand in for "cudaGetTextureAlignmentOffset". In that case, the long form is what I want.

We handle these principles effortlessly with our use of "he" vs "John" vs "John Smith" vs "the John Smith you went to highscool with" but for some reason have trouble with them when writing code.

Alphabetically {a, b, c} × {Min, Max} is soo much nicer than the converse. Especially in lists dozens of items long.

Point-free syntax has a different kind of namelessness, where if you have a single thing, you don't have no name it. And the $0 is really a limitation of the language, nobody ever though it was a good thing.

Underscores are better for readability other kinds of things like unit test names or filenames. Because humans tend to shortcut, it becomes camelCase for everything, including other inappropriate attributes out of laziness, which is aggravating. It's too bad that distinction has not been properly subjected to rigor yet.

http://www.cs.loyola.edu/~lawrie/papers/lawrieICPC09.pdf