#objective readability

[mentalisttraceur-software]

Over the last couple days I guided someone through implementing a basic "bingo" game in JavaScript, and it was a good reminder of just how much

technical knowledge,

familiarity with idioms and conventions and language that programmers use, and

trained cognition

it takes just to write any substantial software.

And more importantly, most importantly, very importantly: how unintuitive programming languages are, how much they perpetuate stuff that programmers have to be mentally broken into, that isn't obvious until you've had it explicitly explained.

Like "for" loops, the kind you find in C or Java, with two semicolons in the middle, are horrible interface design (if the goal is the best interface for humans working with higher-level concepts, rather than the best tiniest-increment improvement over previous methods for manually guiding the CPU instruction-by-instruction through an iterative loop). Python-style "for foo in bar" is much closer to reasonable. Could be even clearer if it was "for each foo in bar".

Do-while loops? Would be better if the syntax was `do ... repeat while`. Six characters could smooth the learning curve for that one construct profoundly.

More substantially than just syntax though, I have profoundly increased appreciation for the point made by Rich Hickey (creator of Clojure) that variables - places where values are stored and possibly are later overwritten, are inhuman unintuitive bullshit. He puts it more nicely than that. I appreciated this point when I first heard his talk, but it gains so much revealed wisdom when you see a programming novice think of a variable as a placeholder for code which is lazily reevaluated each time it is used rather than as holding the result of that code. I'm now convinced that it is a serious possibility that a programming language where everything is lazily evaluated and variables don't exist and mutable values don't exist isn't just easier to audit and optimize, but genuinely easier to understand and learn unless we've already had our logic severely bent to match all these programming languages which are optimized to express computer implementation details instead of human reasoning.

[mentalisttraceur-software]

Another great example of abbreviation aesthetic brain damage: the Slack API message block type for sending Markdown text is called "mkdown".

Or was it "mrkdwn"?

Pause here to recognize that this is yet another problem with most abbreviations. It has been less than two week since I last saw this string, and I could not tell you if it's "mkdown" or "mrkdwn" if my life depended on it. I just remember that it was six letters of typical needless abbreviation bullshit. Gun to my head I'd gamble that it was the one without any vowels.

Again, this is a Hell's Kitchen for Programmers moment. If this was food Gordon Ramsay would tell you "oh fuck off" if you worked in his kitchen and brought him this shit.

God forbid we spend a couple extra characters in a string that is almost never manually typed and gets placed into huge plaintext JSON messages. No, no, please, continue micro-optimizing out two characters out of thousands.

What makes this worse is that "mkdown" or "mrkdwn" or whatever-it-was is NOT short for just "Markdown". No no no. It stands specifically for Slack's Markdown flavor, with Slack-specific extensions and incompatibilities. It's almost like they used the fact that it was their Markdown flavor as a rationalization in favor of a bullshit unique abbreviation, without even a hint of trying to critically loop that idea back on itself as a check, since no abbreviation of "markdown" suggests "our specific markdown" nearly as much as it suggests "the word markdown as generally understood, just abbreviated".

Anyway, what Slack should've done was call the message text type "markdown.slack.com" or something similar - that would have been extremely unambiguous and maximally helpful in several ways. It clearly indicates that it's the markdown flavor that belongs to slack (specifically the Slack that can be located at "slack.com", and not any other possible future or present or past use of the word "slack"). This indication in turn raises the alarm that their markdown is somehow different from normal markdown. They could put a precise description of their markdown flavor on a webpage accessible through the FQDN "markdown.slack.com". And you could throw "markdown.slack.com" into Google and trivially locate information about their specific markdown flavor.

And if by some chance you actually have a good reason for why the "name" (uniquely identifying string) for a text format type shouldn't look like an FQDN, then something like "slack-markdown" is still vastly better than dropping a couple letters, and retains most of the above benefits.

[mentalisttraceur-software]

Today's instance of the `sed` dilemma:

s/.* href="\([^"]*\)"/\1/

versus

s/.* href="//; s/".*//

I mean... I think this one's pretty easy: clearly the second one. But I had to put some actual thought into verifying that it's inherently "lighter" on the working knowledge and precise parsing it demands of the human reader.

[mentalisttraceur-software]

@kata4a replied to the post about dashed, underscored, and mixed-case names:

it seems like the underscore looking more like a space would be a pro?

At first glance yes, I thought so too, but an identifier has the job not only of separating the words that comprise it, but also of holding them together.

Compare

foo_bar_qux abc def_ghi

foo_bar qux oui_def wbh

foo bar_qux_poo qkw_wjw

versus

foo-bar qux wuw-uwu opa

foo-bar-qux htj ana-fra

foo bar-qux eie-jkl-meh

Now also consider the great underscore destroyer: highlighting.

[mentalisttraceur-software]

Controversial opinion, but

names_with_underscores

are objectively more readable than

namesWithMixedCase

and you can easily prove this to yourself by taking a long break from regularly reading each one in turn, and then getting used to them again.

Your return to reading underscored names is going to be almost effortless and instantaneous, no matter how long it has been since you last read them.

But you will feel the subtle extra visual and mental effort and slowness of pulling apart words after enough time away from reading camel case.

[mentalisttraceur-software]

I get annoyed with almost every opinion or claim about why code is or should be styled a certain way, since it is often clear the speaker cannot distinguish between visual parsing ease that comes from habit and familiarity, and visual parsing ease that comes from objective factors.

[mentalisttraceur-software]

Quick, which of these headers did `setmode` come from?

Trick question, because there is no way to answer that question in an acceptably small amount of time and overhead (short of already having the answer memorized or already having that file open with your cursor on the `setmode` function in an IDE that already knows about what's in those headers and can show you which one a symbol is from).

The actual answer is "this is why we add a comment to every #include line explicitly mentioning what we're using from it".

[mentalisttraceur-software]

`thrd_exit` is such a perfect example of abbreviation aesthetic brain damage.

Third exit? What like a third variant besides normal exit and quick exit? That would be weird. Oh! No, it's thread exit.

If I was running a reality TV show like Hell's Kitchen but for software development, and someone brought me "thrd" as an abbreviation for thread this is where I'd say "oh fuck off" the way Gordon Ramsay does all the time.

Seriously. To everyone on the C11 committee who came up with this or allowed it through, fuck off. What the hell is this shit? God fucking forbid a C programmer has to find any vowel besides "i" on their keyboard, or type a hundred more keystrokes over their entire programming career. No, no, let's outsource and multiply that cost over every read and interpretation of the code instead.