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.
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.
> 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.
Don't do it 15 times, though, because then it's going to slow down onboarding more than the benefit you get.
Nothing was named according to what it did either, I think our deploy tool was Carnival? Just codenames everywhere
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.
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.
Then it's working. That is exactly the point of code names.
What's that? Oh, so it's like this. Why not call it that?
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?
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.
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.
Is it not just the computer world which is the odd one out in coming up with needlessly confusing names?
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...
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.
"string of characters" as a concept substantially predates the first computers: https://www.google.com/search?q=%22string+of+characters%22&l...
Otherwise, please prioritize readability.
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.
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.
Perhaps, but 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.
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)
Thank you Tim! You did us a solid.
Over the years I’ve learnt to prioritise readability and to never abbreviate. Tab completion makes it a non-issue.
How did I do?! :D
ⴵ ⵛ ꘜ ⵣ ꕤ ꖜ
ꘖ ꧮ ⴲ Ⰴ Ⰺ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".