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.
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.
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
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.
> 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.
… 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.
> 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.
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
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) -> _ //...;
The result is legible, the concept is meaningful, and a naive reader could make sense of the variables and operations. No cognitive / conceptual overhead.
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.
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.
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).
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.
> 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.
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.
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.
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 :)
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
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.
efitz|1 year ago
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.
tshaddox|1 year ago
GuB-42|1 year ago
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.
ncallaway|1 year ago
> 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.
marcusbuffett|1 year ago
Nothing was named according to what it did either, I think our deploy tool was Carnival? Just codenames everywhere
BWStearns|1 year ago
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.
drewcoo|1 year ago
Then it's working. That is exactly the point of code names.
diob|1 year ago
What's that? Oh, so it's like this. Why not call it that?
lawn|1 year ago
readthenotes1|1 year ago
deathanatos|1 year ago
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?
kstrauser|1 year ago
serbuvlad|1 year ago
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.
seabass-labrax|1 year ago
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.
ketralnis|1 year ago
Sweepi|1 year ago
cxr|1 year ago
Empact|1 year ago
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:
The result is legible, the concept is meaningful, and a naive reader could make sense of the variables and operations. No cognitive / conceptual overhead.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...
liontwist|1 year ago
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.
throwuxiytayq|1 year ago
mouse_|1 year ago
Otherwise, please prioritize readability.
p1necone|1 year ago
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.
marcusbuffett|1 year ago
brudgers|1 year ago
wruza|1 year ago
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.
fundad|1 year ago
not2b|1 year ago
einpoklum|1 year ago
Perhaps, but a meaningful name is better than an arbitrary made-up name.
9rx|1 year ago
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.
tshaddox|1 year ago
unknown|1 year ago
[deleted]
david-gpu|1 year ago
Thank you Tim! You did us a solid.
stephen_g|1 year ago
SPBS|1 year ago
beastcoast|1 year ago
Daneel_|1 year ago
Over the years I’ve learnt to prioritise readability and to never abbreviate. Tab completion makes it a non-issue.
johnea|1 year ago
lgas|1 year ago
ghjfrdghibt|1 year ago
einpoklum|1 year ago
wruza|1 year ago
aragonite|1 year ago
kaptain|1 year ago
wbl|1 year ago
hakuseki|1 year ago
marcusbuffett|1 year ago
Terr_|1 year ago
deskr|1 year ago
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".
stevebmark|1 year ago
polotics|1 year ago
unknown|1 year ago
[deleted]