hckrnws

I really don’t like this idea if you are sharing this code base with anyone else.

I work in one of the magnificent seven and the culture here is codename crazy. Everything has code names, of course: every project, every release of every project, every component or subservice of every project, every internal tool, and often minor features that address some one-off problem in any of the above.

I am sure that these names solve some kind of brevity problem for the people on those immediate teams, but it is a nightmare for everyone else.

It is impossible to reason about or even understand have the statements made by members of other teams in a meeting or communication because every other word they use is a code name for something that you’ve never heard of and the name doesn’t bear any resemblance to what it represents. It drives complexity through the roof.

It depends whether the increased brevity is worth the decreased intuitiveness. Consider that all words and names are made up in order to trade intuitiveness for brevity.

Excellent point; I think there is also an analogy to be made with the linguistic distinction between synthetic and analytic languages. Broadly speaking, analytic languages feature longer sentences with lots of brief, generic words, whereas synthetic languages have shorter sentences in which each word encodes a complex idea (for example, using prefixes or vowel changes). English is towards the middle of the continuum, with both analytical and synthetic characteristics.

I prefer code names over acronyms. Like code names, acronyms are meaningless to the uninitiated, but for me code names are more memorable. Here, I don't know what "EPD" or "SAN" mean and these are terms I have to get familiar with when reading the code base, just like "kep". I get that EPD and SAN are probably familiar terms to chess people, but the idea there is never a code base where you don't have to get familar with some vocabulary.

Unlike acronyms, good code words have some emotions attached to them, maybe some backstory or theme. For example, Android versions are alphabetically ordered desserts, there is some consistency to it. When first told, you can picture it in your head, even taste it, this can help with memorization as it is not just a random 3-letter string. Even with the nonsensical "kep", it has a nice sound to it, and in fact, I have memorized it, it is a combination of a hmm... chess stuff and... san? (looking up) oh yes, EPD and SAN.

I have found Android codenames to be a nightmare. Docs will sometimes refer to a codename, a version, or an SDK level. Why do we need three pointers to the same thing?

Ubuntu is the same, unless you happen to know the previous release and know they are in alphabetical order. Debian is even worse: not in order, no one ever uses the version number.

Those are abbreviations, not acronyms.

They are acronyms. Why do you think differently? And acronyms are abbreviations. If you want to argue more you could state they’re initialisms, but SAN is standard algebraic notation so it’s definitely an acronym, while EPD could be argued not, but instead to be an initialism. In any case Wikipedia says it’s not a settled matter so why even argue about it? https://en.m.wikipedia.org/wiki/Acronym

I’m not OP, but I’ll answer the question for me. I think differently because I was taught differently in English class about 40 years ago. The wikipedia page makes a weak argument.

What do you think distinguishes an acronym from other abbreviations?

Acronyms and initialisms are formed by each of the first letters of a phrase. Acronyms are distinguished from initialisms by being pronounced as a word rather than saying each letter individually. Abbreviations are shortened words or phrases: apartment=apt., captain=cpt., corporation=corp., minute=min., etc.

I feel like that complaint is somewhat addressed by the blog post itself:

> Obviously don’t go crazy with it, but it’s a tool I’m happy to have added to the toolbox.

It sounds like your company culture has gone crazy with it, which, yea, I would think it would make it hard to reason about.

I think this kind of naming approach could be...reasonable in a shared code base, if used very sparingly and well documented.

Yah. If your big project has 2 kinds of objects, handles, designators, whatever that are used frequently... and their alternative english names are awkward, long, and/or misleading... give them a short pronounceable name. I endorse this 100%.

Don't do it 15 times, though, because then it's going to slow down onboarding more than the benefit you get.

Oh god yeah I’ve been in this situation too. Working at Apple it was like “is everyone in this meeting cleared for Tigris?” And you’d be like “I don’t know, what the hell is Tigris”, and then it turns out after you check your clearances it’s just iOS 13, which is obviously no mystery that after 12 there will be a 13. Just call it that!

Nothing was named according to what it did either, I think our deploy tool was Carnival? Just codenames everywhere

In general I completely agree that code name overload is dreadful. But I think in this case, where this pair is so fundamental and used so frequently in the codebase, I think I would probably permit it. Beware codename creep.

I dunno carnival seems like an apt name for a deploy tool at some of my past jobs.

That's definitely a possible failure mode, but I think it's preferable to having DataProcessingWorker, IngestService, ProcessingService, DataLoader, etc. Because, you eventually end up with all of these names and it's just as hard to guess what happens where as if they were named after fruits.

At least for me having too many names that are nearly semantically identical is worse than names that are a little (or even a lot) weird. We stare at names all day and if everything is named `YourCompanyNameMessageDataProcessingService` searches get annoying and it's easy for your eyes to start to glaze over.

If you name stuff like, say, Shucker, you have to ask "wait, wtf is the Shucker service?" Someone explains "It unwraps the GRPC messages and puts the contents on a queue. It's like shucking an oyster I guess? Yeah, we know it's a dumb name." But now you have a unique handle that's not likely to collide with other services.

If you can find a straight laced informative descriptive name that's unlikely to collide in the future that's great. But I'd take a funky name that immediately makes sense once you explain it (reference/pun/acronym whatever) over some 2010s java-class-name-looking beige blob of text any day.

I’m also in agreement with this.

Give me unique and memorable over generic-looking-with-the-merest-bit-of-information.

Used to work at a place where every repo, every service, etc was all CompanyShortNameThingDoerServiceRequester and similar, surprisingly unhelpful. I don’t want the 100th CompanyDataIngesterService because they all blur into one.

At least if someone goes “oh yeah the Oyster service will give that to you” we know precisely which one we mean.

In my personal experience, libraries/code that is widely applicable is what benefits from having a great weird fun name. No one wants to deal with a one off service you decided to name Hecate with no reason or broader appeal.

> It is impossible to reason about or even understand have the statements made by members of other teams in a meeting or communication because every other word they use is a code name for something that you’ve never heard of and the name doesn’t bear any resemblance to what it represents

Then it's working. That is exactly the point of code names.

It's one of my big issues with lots of things, even outside tech.

What's that? Oh, so it's like this. Why not call it that?

I've only worked at a company with around 300 employees and I've still struggled with this issue.

I figure it would be awful hard to communicate without the semantic shortcuts that comprise a vocabulary

… a company I once worked at named everything after characters from a certain TV show. Effectively the same as a made up name. Let's just say one of the character's name was … a tough one to pronounce. And it caused endless "what's a … Kep?" type questions.

The CTO at some point later on decreed "enough; descriptive names, not made up things" … and the experience was such that I agreed with the decree, and I've sort of felt that way ever since. I've given a few names sparingly to a few things, but mostly a.) they have some connection to the named thing and b.) I reach for it when the purpose isn't clear yet and thus "descriptive" can be hard to come by.

You could have named it a "PoMo" (portmanteau of position-move), if you're tired of typing.

I'm also a bit surprised since the examples are Rust? Some of the naming is sort of "Hungarian notation"-esque. Why not let the type carry that information, and strike it from the name?

That's why my servers tend to have boring names like "web-23" now. Given them fun names is fun, up until it isn't, and then it's really freaking annoying.

If it occurs often enough, yes!

The human brain finds unexpected or weird words a lot more memorable than expected words.

grep is better than find "find-regular-expression"

awk is better than "execute-command-on-regular-expression"

perl has nothing to do with pearls

If it's a common command, concept, function, etc. that appears in may places, give it an odd name!

Document it thoroughly!

And don't go overboard. When everything is special, nothing is, with the added disadvantage that nothing is "readable" either.

> grep is better than find "find-regular-expression"

I'm not sure if you are familiar with where grep came from, but in short it is an abbreviation of a command in the original UNIX text editor: g/re/p - g for global command, re standing for your search query and p for print to screen or teletype. In that way, it is nothing more than an anachronism that would have been immediately obvious to anyone working in a UNIX environment at the time.

AWK and Perl are just programming languages. I think they have made up names because programming languages are singular entities, but have too many characteristics to condense into a short name. That's different from a function, which in conventional style does exactly one thing with only one or two characteristics and so can have a 'short' and descriptive name a few words long.

I don't disagree with your argument, but I wanted to point out that the examples you gave were made-up names out of tradition or necessity, not because they were intentionally designed to be memorable.

Choosing the name grep because it is easily recognizable as coming from the command it is inspired by is literally "intentionally designed to be memorable".

I have a lot of conversations like "There's a technique called 'secure computation', which confusingly is not just computation that is secure", "They're building affordable housing, which confusingly is not housing that is affordable", "I was on a cross-country flight, which confusingly is not a flight that crosses the country". Using a different word entirely can avoid that problem

The UK government defines 'affordable housing' as that which is available for at least 20% below the local market rate. Cross-country flights, at least where I'm from, do indeed cross the country on one axis or very nearly so.

Is it not just the computer world which is the odd one out in coming up with needlessly confusing names?

No, it's not just the computer world.

Affordable housing where I live is a specific thing. Below-market-rate housing purchaseable/rentable with specific income requirements. Some number of units in new builds are usually required to meet this requirement. Your example sounds similar, it is also specifically defined and not just housing that is affordable but rather it meets specific requirements.

A cross-country flight to a pilot licence is a flight that goes greater than 50 nautical miles one-way. During flight training you need some number of these so you talk about them a lot during that training and it's mentioned a lot in the regulations.

And as I guess you're aware secure computation is also a term of art in CS for a specific thing.

I'm sure every field has terms of art that overlap with things whose words don't precisely describe. A chef's knife is a specific shape/class of knife, not any knife used by a chef. Law is full of them. There is a wealth of examples.

Thank you; I appreciate the explanation. I suppose the cross-country flight is so named as to preclude student pilots flying around and around in small circles to qualify?

I don't know why it's named that way but you need some number of cross-country flights and hours because there are skills that you pick up doing that (several kinds of navigation, fuel management, weather management, flight planning, map reading, etc) that you wouldn't by flying in circles or by spending time in the pattern (looped takeoffs and landings, which you do also need to do a fair amount of but builds a separate set of skills)

"cross-country" has a similar meaning in many contexts, skiing, biking, planes, running, etc. I believe it was originally coined in running and then extended to other pursuits. The 'country' part of the term comes from the sense that means "non-urban land" rather than "geopolitical state".

I regularly cannot remember if its "grep" or "greb". Never had this issue with Windows' "findstr".

It's not "findstring"? I'd never remember that.

The 'p' is for print.

This is good if you're good at coming up with names that are good, even if they're inscrutable. If you're not so good at it, or do too much of it, then you end up getting a situation like the Urbit ecosystem.

This didn't sit quite right with me and I think I've pinned down why.

The nature of code is that it is communication: it communicates action to the computer and behavior to the reader. Variable names are not for the computer, they are for the reader, so, whenever possible, the names we use should be meaningful to the reader.

If the name requires specialized knowledge, such as "what does this name mean," it is lingo, which is sometimes necessary, but should be regarded as a smell, as it is often better to use language which does not require specialized knowledge, so that the reader will be able to make sense of it without a thesaurus.

According to the concept Domain-Driven Design, we should be using names from the domain itself in the program. So what could be the proper name here?

Well, EPD is short for Extended Position Description, which is a notation for representing a particular board state. SAN is short for Standard Algebraic Notation, which is used to encode a particular move.

So an EPD SAN is a particular board position when a particular move is applied to it. I propose to call the combination a "play" which is the act of moving from a particular board position. The code would then be:

  let difficulty_by_play = //...;
  let existing_plays = //...;
  let unique_moves_by_play = //...;
  fn play_to_condition((epd, san_plus): &Play) -> _ //...;

Cleaner code, I would claim.

https://en.wikipedia.org/wiki/Domain-driven_design https://en.wikipedia.org/wiki/Extended_Position_Description http://www.saremba.de/chessgml/standards/pgn/pgn-complete.ht...

The more abstract and technical the subject matter the less likely that it will mirror a familiar real world experience and have a good word.

Using a real world name can actually be distracting because it may suggest attributes and behaviors which are not true of the thing.

This is why math papers use Greek letters. There is no words for “the amount of space where if the function is close enough than the cube of that function value will be within the initial tolerance requiring” so they just use “delta” and you learn the exact meaning of delta from its definition and usage.

I think this advice about “readable code” comes from every day business problems where there is a close correspondence between code processes and business processes.

Complex programs require expertise to understand, and only hubris would make you think longer names would substitute for studying the subject. Even “string” is technical jargon.

> Even “string” is technical jargon.

"string of characters" as a concept substantially predates the first computers: https://www.google.com/search?q=%22string+of+characters%22&l...

Yes, but if you don’t already know programming or a related field you won’t know that.

So according to modern naming convention it’s a bad name because of gate keeping, ivory tower, etc along with: thread, kernel, float, register, ascii, etc

We have to invent domain-specific language when there is no existing term for an important concept. Each of the terms you mention except ascii (which is an acronym) is imbued with contextual meaning: thread of execution, kernel as in essential core, float as in floating point, register is in that which records and reflects. I’m willing to bet I will find similar pre-computer uses if I go looking.

Which is to say they represent a different approach than simply making up a word devoid of meaning.

Cuts both ways - often it's useful to do the opposite and inline the type to avoid declarations that make you jump around. Especially in the case of small, one-off, tuple-like structures. But I'd keep the Kep.

This works great if you're absolutely certain no other poor sap is going to have to work with your code. I do this myself for personal scripts!

Otherwise, please prioritize readability.

I think needing to work out what it is by asking someone or reading documentation or whatever is a feature, not a bug here.

If you instead used a word that kinda described what it is without being able to explain specifics people might make assumptions. If they have to go "what the hell is a kep" and then ask you then you can be sure they'll find out about the implementation that's slightly different from other keps, or the weird bug that happens when you do y, or the handy library for doing kep things or whatever before they waste time going down the wrong path.

Obviously this sort of thing should be done sparingly, otherwise you end up with a completely incomprehensible codebase - but for specific things are are genuinely novel I think it could help with overall grokability rather than hinder it.

It’s one made-up name in a 30,000 line codebase. I think if anyone else ever works with the project they’ll have a lot harder things to catch up on than this convention

Documentation is probably better than readability because readability makes a lot of assumptions arising from being close to the code...for example, Swedish names are not gonna be all that readable for most programmers (this holds true for English names as well).

wasn’t a mouthful like MoveFromPosition

PosMove, but nothing wrong with MoveFromPosition either.

I also easily get annoyed by mouthful typing, so I usually do the following: write code in short identifiers and then rename them after I finish.

I wish dev envs could store two representations for an identifier, one short and one long, so one could easily switch between these (and also local/personal ones, or name comments at least). But that’s rocket science for text-based sources.

I like this and seeing Kep reminds me of kip, a currency, and that got me thinking that currency names is a fun source of "made-up" names for things.

Sure, a made-up name is better than no name, but a mnemonic, logical, understandable name is far preferable. Perhaps just more thought is needed.

> A Made-up Name is Better Than No Name

Perhaps, but a meaningful name is better than an arbitrary made-up name.

> a meaningful name is better than an arbitrary made-up name.

What's the difference? All names are ultimately arbitrary and made-up. For what it is worth, my best at attempt at interpreting this is that a meaningful name is an arbitrary, made-up name that also comes with a reasonably precise definition. In which case, the idea of choosing a meaningful name is the intent of the article.

> All names are ultimately arbitrary and made-up.

You could say that all of human experience is arbitrary and all ideas are made up...

The difference between arbitrary and non-arbitrary in this respect is whether someone who speaks the language and has a general relevant technical background would understand what the name means, in principle, or not. If the developer makes up something arbitrary themselves, then they would understand it, and so would one or two people who review the code or interact with it. Anyone else coming onto the scene would _not_ understand what that's about. You would end up with a glossary of bespoke terms not known to anybody else in the world. Now just think what were to happen if each repository of code had its own glossary of this kind. (shivers)

> whether someone who speaks the language and has a general relevant technical background would understand what the name means

You are meaning in the case where there is already a well-known name for what is being described? That is reasonable, but in the article there is no pre-existing term known among those with relevant technical background for what is being described. A new name was warranted. Words have to start somewhere. All the words we know began life arbitrary and made-up.

Not always, for example when the meaningful name is much longer.

I once worked for a company that decided to eliminate internal codenames and instead use the actual brand names used by our customers. It removed a barrier to communication with no undesirable side effects.

Thank you Tim! You did us a solid.

This falls down when you're talking about internal components of products that don't have brand names though.

Oh, no! What shall we do now?

We make up codenames...

This is awful. The alternative isn't "no name", it's a full and unambiguous name (even if it's a mouthful). If you can't come up with a good short name, stick with the long one.

I’ve been on teams that did generic names, and inevitably you end up with names like “work manager service” - whose work? Then it becomes an acronym, like WPS, and everyone ignores it anyways :)

Not my preference, even for personal projects. How many times have you come back to an old project and thought “what the heck is this?”. I know it’s a lot for me.

Over the years I’ve learnt to prioritise readability and to never abbreviate. Tab completion makes it a non-issue.

Aren't all names "made up"?

All words are made up. - Thor

I often remove the vowels, so I'd have probably gone with 'pdSn' as the shorthand for it.

nc... m sr ts rl fn t rd r cd, mn!

> Nice... I'm sure it's real(ly) fun to read our/your code, man!

How did I do?! :D

"real fun" and "your code"; 'y' is... well, vowel-ish at least. Otherwise let's say it was "ur code" in leet-speak.

Oh, I really love not reading code like that!

Instead of "kep", if you want something that visually stands out, there are also lots of fun little symbol-like characters you can use, even when you're dealing with a language where identifiers are limited to ID_Start/ID_Continue (e.g. Javascript, Rust). My favorite collection :)

  ⴵ ⵛ ꘜ ⵣ ꕤ ꖜ 
  ꘖ ꧮ ⴲ Ⰴ Ⰺ

But how do you discuss code issues verbally with others?

If you must pronounce them, all the characters I listed are, in fact, pronounceable (as you can verify by googling them & visiting their Wikitionary pages) since they aren't actually symbols but letters from the alphabets of different languages. :)

"Hey man, I pulled the latest changes and I'm getting sideways Lego brick is undefined, followed by cannot read properties of undefined when reading squiggly prongs."

No multicoocular O? And try Luwian for a real kick: the cutest script.

Be nꙮt afraid.

https://en.m.wikipedia.org/wiki/Cyrillic_O_variants

The article is about (position, move) pairs. Why not call these objects "steps"?

Yeah this is a good shot at using existing verbiage, better than the candidates I came up with at least. Still not entirely self-descriptive, and has some overlap with usage in other parts of the codebase, like in data processing and user onboarding, but maybe that's a fine trade-off to make in order to use a normal word. I'd be equally fine with them being called "steps", but now I'm attached to my Keps :D

A made-up name is fine if (A) your code is private and (B) fixing it later is easy.

Disagree, especially using that first name pops into your mind.

Obviously, if it needs a name or would greatly benefit from a name, give it a name. But have it at least somewhat descriptive. EPDSan, Sanepd, ESpair or some other variation is a lot better then "the first thing that comes to mind".

No one knows what San, EPD, EPDSan, Sanepd, Kep, etc, are. No matter what the word, you have to learn it, and it's a small one time cost, and you're done. The additional cognitive load to learn a made up term is negligible.

don't do that! the word you use a lot in your description is "pair"...