Thread by @ErrataRob

So #SoftwareDevelopment is trending in my timeline, and it's full of crap advice.

Here is an example, the problem with meaningless names, telling programmers to make more descriptive variables. This is absurdly stupid advice.

The actual problem is "empathy", seeing code from the point of view of a stranger, or even yourself a year later when you need to reread the code. You have to put yourself in their shoes, to see your code from their point of view.

A variable's purpose should be derived from its name, not the other way around.

For example, you extract a row from a database containing a person's details. Don't call it "row", call it "person" as the variable name.

Yes, yes, it's a row in the database, so you've derived the name from what's going on. But going the reverse direction, going from "row" to what the variable is supposed to do, is difficult for the person reading the code.

That's the problem with most variables: they are meaningful to the original programmer, but much less meaningful to the person reading the code.

So the prescription isn't "make variable names more descriptive" but "put yourself in the shoes of the reader". Yes, it's a row in the database, but is this the most helpful way to describe the variable?

I say "empathy" here going back to the original meaning of the word (putting yourself in somebody else's shoes), not the modern weepy definition (sympathy for a person). That other person may be future you, so at least put yourself in the shoes of future you.

I forgot, I was also going in this direction: overly long (overly descriptive) variable names are also a pox on programming.

https://twitter.com/Ammon_Ra/status/1517258545443618820

Programming is a choice between variables names that are long enough but not too long. That's why they are compressed, like "pkt" instead of "packet", or "buf" instead of "buffer".

Basic concepts should have basic names. For example, "i" is a GREAT index variable for loops. A "buf" is a great name for a buffer. That's because these concepts are so ingrained to programmers that you only need a hint rather than a full explanation.

But conversely, don't use 'i' for things other than indexes. I saw some code recently that chose "buf" for something that was technically a buffer, so unlike the norm is took me extra time to figure out what was really going on.

Oh, and back to empathy: when choosing a name, maybe instead of "descriptive" choose something "can't be confused with anything else".

I ended up renaming their "buf" to something that wasn't very descriptive, but which couldn't be confused with normal buffers.

Choosing names is ultimately an art rather than a science, but big development organizations (falsely) try to make it a science. They often have rules on how to name things:

https://twitter.com/Ammon_Ra/status/1517257436805148674

The biggest evil is Microsoft's "Hungarian" notation, prefixing variables with their type, such as dwColor, a variable that would store "color" information as a "double word" (meaning, 32-bit integer).

This was actually helpful around 1990 when code in C/C++ was constrained by the limited memory, CPU speed, and inflexibility of interfaces.

In today's world, it's a stupid anachronism that should be gotten rid of.

In today's world, a "Color" is an abstract type holding color information whose representation in memory is undefined, whether 32-bit integr or floating point or whatever.
Hey Microsoft, Hungarian notation is an anachronism, the rest of the world is laughing at you.

Big development organizations have big rules, such as style guides on how their programmers should program.
This is not a science that makes things go better, but an artifact of politics. Big orgs are full of people wanting to tell other people what to do.

Politics are toxic. There are programmers who just want to program. Then there are programmers who want to tell others how to do things. You can recognize them when you go to their office, what sorts of books they have on their shelf.

Some will have books like the essentials of cryptography, that teach technical subjects. Others have shelves full of "process" books, like about "Agile", as they try to convince the organization to adopt whatever they think is good process, style, rules, etc.

I was kinda like that as a kid, very much a nerd who cared about the finer details of things.
But when I was finally put in charge of engineering, able to enforce what I thought was the best "style", I had matured to the point of no longer caring.

The correct style is ultimately simply "things that other programmers won't find surprising" or "just like all the open-source you see on the Internet". Also, code in THEIR style unless you take ownership, in which case then convert to your style.

As you edit somebody else's code, then choose naming conventions that are the same as them. If they use "buf" for buffers, then you should do when adding more functions that manipulate buffers, for example.

On the other hand, when I've adopted code, after running a tool like clang-format to reformat the code, I'll go through and rename variables. It's a good time to do so, because I'm currently an outsider, and am at the peak empathy of how outsiders view the names.

The lesson of the last tweet isn't that I think I'm a better programmer than those jerks who chose confusing names originally, but that I'm in a better position, able to appreciate the code as an outsider in ways the original programmers couldn't.

When we read code, we wonder about the idiots who wrote it. In reality, it was written long ago for one purpose/context and has changed over time passing through multiple hands. What looks like spaghetti crap now could have started life as beautiful elegance.