I'm not knocking the article, but endless aesthetic discussions like this are one of the reasons why I can't wait to leave the industry. The very definition of bike-shedding.<p><pre><code> compare acquire and take_ownership
</code></pre>
Who cares!? Those are both great names for a function...<p>If you put 10 software engineers in a room, you'll get 10 different answers to any question. Every company you work for will be filled with endless "smart guys", ready to spring in to action and nitpick you to death about arbitrary things.<p>It's exhausting.<p>We need more languages that come with rigid rules for things like style, so we can stop wasting time and get on with solving problems.
Another place where naming matters, but for slightly different reasons, is on the command line. If you are naming a program that someone is going to spend much of their time running from the command line, it is nice if you put some thought into how the binary is named.<p>For instance. I've never been able to understand why something like `systemctl` could be so clumsily named. If you have to do sysadmin work, sometimes you will be using the command a lot. If we ignore the fact that I see more and more people typing out entire commands without the use of completion, `systemctl` lacks a short, unique prefix and ends up being quite awkward to type.<p>On my system `sys` is the prefix for 26 commands, and `system` is the prefix for 24 commands. So I end up having to type 7 keystrokes to type systemctl on my system with completion. Sure, I could alias it, but then I'd have to replicate it everywhere, plus I'd be forming habits that just cause more frustration later.<p>Another way to fail is to choose a prefix that has bad typing flow. For instance I wrote a program that has the prefix "aq". Try to type it. Awkward, isn't it?<p>(If you don't think any of this matters, perhaps you shouldn't be the one to pick names for programs that are run on the command line).
> <i>However, I think the more common mistake is using names that are overly long.</i><p>But the most productivity-sapping mistake is names that are too vague.<p>The idea that "names should be as short as possible while still being clear" is a truism I don't think anyone disagrees with. But it's a balance that nobody ever perfectly gets right.<p>So if you're going to err, it's better to err on the side of clarity rather than shortness. E.g. lines like:<p><pre><code> fetcher = repolib.IndexFetcher(args.arch)
counts = collections.Counter()
for file in repo.files:
</code></pre>
Would be better as:<p><pre><code> repo_fetcher = repolib.IndexFetcher(args.arch)
file_counts = collections.Counter()
for repo_file in repo.files:
</code></pre>
It's far more helpful when a line of code tells you what it's doing not just in terms of programming logic but in terms of the purpose of the code, the <i>contextual</i> nouns and verbs. It saves a lot of mental effort when reading and debugging.
Naming things should be as short as possible while still being clear, unless the context of the situation makes a longer name solve some other problem.<p>Naming things should be short as possible while still being clear, unless making it longer helps something else.<p>Name things short as possible while still clear, unless longer helps something else.<p>Name short as possible while clear, unless longer is better.<p>Name short and clear, unless longer better.<p>If longer not better, name short & clear.<p>if_longer_not_better_name_short_clear<p>ifLongerNotBetterNameShortClear
Every code base where naming still matters is a code base that is sprouting new functions.<p>What was “clear” two years ago may be unclear today because we have four times as many functions. Via the pigeonhole principle, there are no short names that are sufficiently clear, and as X goes to infinity even the medium ones become problematic.<p>Use a modern IDE with autocomplete. Try to make the beginning of your names as unique as possible. Few people will have to type in the suffixes.<p>Used to be we would ask other developers what book they would buy all of their coworkers. Answers have changed over time, anything from Brooks to Gamma. But for my money, I would buy them a thesaurus.<p>If you use the same word in two places in the code, they should be sharing code and data structures. If they don’t, you should use a synonym. Never recycle names, and be sure you aren’t recycling. Many people are wrong here, claiming two things are the same but with no code shared, and in many cases I’ve seen, using two different definitions of the same word.
Properly communicating when a requested change is optional is actually one of the most important code review skills you can have.<p>By default, developers assume that a requested change is mandatory. So as a reviewer, it's up to you to explain the difference between a change you're suggesting because it's more concise to use a list comprehension instead of a loop vs a change you're requiring because the change list introduces a race condition that will cause customers to lose money.<p>If you do that, you'll make everyone you work with happier
Using Golang as an example of naming conventions is questionable - this is a language where single letter variable names are <i>idiomatic</i>.<p>I feel like the author missed the obvious; a name should reduce cognitive load as much as possible. Length is one factor that is relevant to this goal, but not the only factor.<p>When a name is too long, this is usually a design issue, not a stylistic issue, i.e. writing Swiss Army functions.<p>Also, takeOwnership is not inferior to acquire, it's just about a wash.
The "clear" part is often the issue. My favorite example:<p>- In Mathematica, if you want to plot a vector field, you use VectorPlot[]<p>- In MATLAB, you use... quiver(). You know, because it holds a lot of arrows. Short and clear, eh?
I think there are main reasons why computer code often have verbose names for functions and variables is that there is a great variance (1) in the application domain of code and (2) the knowledge and background of people who might read and work with your code, making it difficult to assume anything about them. Compare this with the condensed and cryptic music or math notation: they are very inaccessible to readers without many years of training. But that all training, that common understanding, is usually assumed of the reader.
What goes around comes around. We had naming conventions that produced succinct names. They became denigrated and shunned (for no good reason) - use long descriptive names!<p>Now we see that was a bad idea - longer names just allow for more wasted words and are actually less descriptive. Some kind of social or algorithmic convention makes them quicker to parse and understand.<p>I suppose some compromise will be proposed one day. Maybe a prefix to classify the method name, then some short description. Or even an IDE convention to pop up a short description for method names to allow clarification in-situ.
IDE space is free. Copy and pasting a long string takes no more time or effort than a short string. What you stand to gain from shortening a name is trivially small compared to the risk of making a name too short, potentially leading many people to each waste time trying to figure out what you meant.<p>The author's real problem is not about an excess of characters, it's that names are often long because they include redundant or irrelevant information. Still an incredibly minor issue, but there's some legitimacy to that. Better advice would be to keep names informative.
So let's take his example and reverse it. At first glance, what does this code do?<p><pre><code> fetcher = repolib.IndexFetcher(args.arch)
counts = collections.Counter()
for repo in fetcher.get_repos():
for file in repo.files:
counts[file.name] += 1
for repo, count in counts.most_common(10):
print(repo, count)
</code></pre>
Can't really tell, the names are too short. It's clear to him <i>right now</i> because he's intimate with the code. I'll bet it won't be clear to him in 6 months after he's crammed 100,000 lines of unrelated code into his brain. It certainly won't be clear to some poor sod with zero familiarity who has to come in behind him and maintain it.<p>His basic premise is correct: Names should be as short as possible while still being clear. Unfortunately he didn't follow his own premise. Err on the side of too long but clear, because maintenance is 90-99% of the project's life cycle and reading code is at least 5x harder than writing it. You should name variables/methods as if you won't be touching it for 6 months and you want to be able to have a decent understanding of what it does within 5-10 seconds of reading it.
Swift is one of the only languages that actually makes long names work.<p>Rust's flavor of variable shadowing is a great way to support developers to keep names short.
> Some developers do use names that are too short. However, I think the more common mistake is using names that are overly long.<p>I agree 100% with this. Overly long names are very painful to work with.<p>But naming things is very hard. I'd be happier if people just adopted a <i>consistent</i> naming scheme that is predictable. I'd put up with the crazy long names in exchange for that.
My top priority when naming things is discriminated grep-ability: if/when I want to refactor my code and find all occurrences of a certain function call, will this name allow me to do it in a way that is distinct from other names?<p>After that I mostly agree with the author that short and clear are the next two priorities.
Sure, brevity is the soul of wit and all that. Just so long as you don't go dropping letters from the middle of words because you're going for the unixy aesthetic. That style is an anachronism from an era when symbol length was limited, it doesn't belong in modern code.
The hard part of naming is none of these things. The hard part is dealing sensitively with snowflakes who think naming doesn’t matter and instead of saying this to your face, they privately have conniptions trash talking you behind your back when a minor improvement is suggested.<p>They’ve made it so that naming cannot be discussed. If you see a horrendous name and suggest an improvement, there’s no overt response, but later you hear from your friend that the poor namer is accusing you of wanting to die on a hill.<p>Dude. It was just a suggestion. And it was labeled as a nit. You don’t have to take it, even though we’d be better off if you did.<p>So I’ve all but abandoned ever suggesting improved names, unfortunately. Being a good team player is more important. I name my stuff well, but what others do is up to them.
This comes into tension with making names as clear as possible while still being short. Frankly, I don't find coming up with short names for things to be easy, let alone good names even when taken to the extreme.<p>Whether something is too short depends on your context. requests.get might be ambiguous for someone who has never seen the code base before, but will quickly get obviously with a little exposure, so does the code base have dedicated maintainers?<p>The skill of good naming isn't distributed evenly and OP's names are pretty good, so I'd be happy for them to come along to my code base and rename things as long as it was within other constraints (not consuming too much time, doesn't break api, etc).
Since fetching webpages is very common we know `send_get_request_and_receive_response(url)`
is wordy. Of course you need to get the response.
But in some other area it might be obvious so naming the function with more words could be useful.
I definitely agree…the opposite of this takes a lot longer for me to read and understand.<p>I think the point includes reducing unnecessarily complex terminology as well. Do we have to “execute” a function or can we just simply “run” it?
I tend to agree, however, I typically tell people that if you see longer function names, you should watch out for complexity. In fact, if I have to write some overly complex code that I can’t isolate for some reason, I will usually try to show it in the names being extra long.
What is clear depends on context, familiarity, and expectations. It’s not an objective measure when those vary (and they often do vary). In addition, some amount of redundancy is useful for guidance and to avoid misinterpretations. It’s more an art than a science.
Well, of course. This could also be said as "use long names when short names can't be clear enough." Don't be afraid of long names since we have modern IDEs with competent auto-complete. Also, long names go a long way when searching a codebase.
In the age of IDEs I don't even care about the name. Call everything "function" and write a description right above it in comments that can be picked up in autocomplete. If not, I'm probably not bothering with your library.
"Fresh fish sold here today"<p><a href="https://kathakids.com/folktales/fresh-fish-sold-here/" rel="nofollow noreferrer">https://kathakids.com/folktales/fresh-fish-sold-here/</a>
Ed, says the variable name is too long. Sebastian says is too short. Waldo is not sure. A variable name should be easily inspected across the whole project using grep from the root directory of the project.
Of all the things I have to do on a daily basis, naming things is nearly at the bottom of my give a shit list. If you named a particular thing "FRED", I wouldn't care. I can read the code and get the context.<p>A bit extreme, but the point is that all of this is just a waste of time. A WASTE OF TIME. Name it close to what you think it is and move on with your life.