A good name is like a good car. Is a race car a better car than a truck? Lot of trade-offs to make.
You want names to be short, so you easily write and read them. Especially if you use them a lot, it's useful to use abbreviations, like x, e, i, z.
You also want names to be easy to understood, therefore, longer than few letters. So, "count" instead of "cnt" or "c", in short, no abbreviations.
You want names not to clash. So every name should be a unique 64-character long identifier, as far as distant from anything else as possible. However, they should also be optimized for the tree search when using completion.
You want names to describe similar things with similar names. In particular, my pet peeve, how to name objects that are "essentially the same thing" but only different structure so I could better manipulate them, like converting list of tuples to a dictionary? From purely domain point of view, they should not even have different types! And did you know that every Monad is an Applicative?
Should the name reflect the result only or also the path that was taken to get to it - "customerList" or "customerListFiltered"? Or perhaps just "list", because the function is not specific to customers. It's local context versus global consistency.
There are minor problems as well. Underscore_case looks ugly, dash-case is mostly not supported, camelCase is just weird when you want to have anotherCamel (now strangely upper-cased), and CapitalCase looks ugly with acronyms. And should we put adjectives in front or at the back? And why are the elements of EMarble called RED, GREEN and BLUE?
> You want names to be short, so you easily write and read them. Especially if you use them a lot, it's useful to use abbreviations, like x, e, i, z.
when I look through older C codebases (Python, Linux), I often notice the extremely short and cryptic names. I wonder whether this practice is an artefact of a time before auto-completion & automatic refactoring?
These days, you can use meaningful names without much typing. From a reading perspective, I believe that longer names (within limits) are easy to parse. Humans see words, not characters.
--
E.g. When I first understood that argc means "argument counter" and that argv stands for "argument vector" it was a little revelation to me.
This has probably been said a dozen times already, but short symbol names are indeed acceptable in various situations, including but not limited to:
- Where they are actually correct, such as dimensions (x, y, z) or vectors (j, k, l, u, v, w).
- Other mathematical symbols (N, M, e, t). Maths is also a special case in which I'm personally willing to do away with usual variable naming conventions, for example when translating formulas from a scientific paper into program code.
- Very short code, e.g. lambdas (lambda x: x2), list comprehensions ([p.title for p in posts]) or simple loops.
If you look at SQLite, you'll notice that most variable and struct field names are short and cryptic, and that library is still considered a high-quality piece of code.
Regardless, I don't understand all the downvotes you're getting.
IMO short names are perfectly acceptable and even preferable as a local variable names withing short functions, when context is obvious and everything fits onto one screen. I would prefer
for (int i = 0, len = string.length(); i <= len; i++) {
char c = string.charAt(i);
if (c == '\t') {
return true;
}
}
return false;
rather than something like
boolean tabFound = false;
int stringLength = string.length();
for (int characterIndex = 0; characterIndex <= stringLength; characterIndex++) {
char character = string.charAt(characterIndex);
if (character == '\t') {
tabFound = true;
}
}
return tabFound;
Naming a variable solely after its type is never particularly useful. A name like `currentChar` would probably enhance readability. Of course if your code is just 2 lines long, `c` works just fine (that's not usually the case though).
You should probably abstract away some of that logic though (and `string` isn't a great variable name either):
If the functionality you're writing is truly that abstract, an abstract variable name is fine. Your example didn't include the method signature though, so I assumed it was a part of some larger (concrete) code block.
Yes. Very much yes. My personal rule is to _always_ use single-letter names for Python comprehension indices, because line length is the biggest enemy of readability there.
In my experience, one-character variables are serviceable, even preferable, when you're piping data, like Streams in java, or all the equivalent functions in rust. So long as the starting input's type is clear, the "capturing" variable can be just the first letter of the type.
I personally prefer short and cryptic names for things that are used very often, but don't shoot the messenger. My main point are the trade-offs.
Some of that is from mathematics, for example (random code from the Internet):
reverse2 xs = go [] xs
where
go ys [] = ys
go ys (x:xs) = go (x:ys) xs
In general, more abstract you get, the less important it is to devise long names, because things are going to be abstract anyway. Often, all you can tell about the object is already encoded in the type system.
Even in current practice, people prefer "log.info(..)" to "centralizedLoggingSystem.informationalMessage(..)". They prefer "Exception e" to "Exception unexpectedlyFailedToWriteAccountingFileException". We also prefer to write "a * b" instead of "a.multiplyBy(b)".
Sometimes simply the global consistency trumps the local context.
> E.g. When I first understood that argc means "argument counter" and that argv stands for "argument vector" it was a little revelation to me.
This is something every hello world tutorial should point out, but obviously most of them leave a lot to be desired. Or "argument count," as I know it, not "counter".
To me, most abstraction used in computing is done to provide way for a reductionist view of something. Abstractions don't have to be reductions but in practice, that's what they're typically used for.
Because of this, whenever you're reducing something you inherently peel off information and it's lost to 'simplify' something. This is where all sorts of forms of documentation come in handy: they provide a venue to retain and share some of that lost information you think might be critical and explain those 'simplification' assumptions.
In the above, information for reductionist abstractions often get lost over time when people make assumptions and don't share them in some form. Once you understand the original meaning--information that was lost, often times if well designed, everything falls into place for understanding fairly quickly.
I recently saw a post somewhere explaining why "uppercase" and "lowercase" described characters due to historical context where on printing machines, what we know as uppercase letters were stored in the top of the case while what we know as lowercase letters were stored in the bottom of the case (hence the upper and lower cases). Most my life I just assumed "upper" meant "bigger" and lower meant "smaller." In this particular case, that lost nomenclature information didn't add much value (although interesting). In some cases, it does (like the argc and argv information pointed out). Choosing what information to reduce and carry forward is an art form. You also have to be careful when teaching about what assumptions you take for granted that most don't start with.
I'm a believer in understanding at least one level beyond what an abstraction system is doing for me. It's not the most efficienct thing, but it demystifies the abstraction and when you run into hurdles introduced because the structure of that abstraction, you know why and often can devise ways to fix it. It's not always possible and in some cases isn't worth it.
Most modern software development has so many high level abstractions that understanding even one level down is typically impossible for any sane person given typical resource constraints for a given API. Because of this, we run into all sorts of messes where were drowning in abstractions (that aren't very standardized or widely adopted, instead composed together in case by case basis) we don't understand (i.e. complexity). That's all well and all until those abstractions fail and you're the person responsible to repair/mend them back into usefulness for a particular case--then it's a nightmare.
Personally, I can stand abbreviations so long as they're pronounceable. I think phonetic syllable-granularity abbreviations are an optimal tradeoff. argumentVector is silly to be writing in full all the time but argv is infuriating.
When I parse code I'm mentally reading to myself, so argv is deplorable gibberish that has to be translated to "arg-vee". It's like traveling over rocky ground, one step is easy enough but over a distance it really slows you down. argvec saves almost as many letters, is way more readable, abbreviates both words down to the same scale, carries more semantic meaning through for a newbie, etc.
Some English words can't be phonetically abbreviated and I think those are better off written in full.
x is a variable name I still use quite a lot. Because it is quite meaningful as 'a meaningless parameter that is just a variable'. Same with y and z, though less often.
I'd also say that short names are sooner a product of line-length limitations than refactoring. Having to spread out every single statement over many lines because your reference a 12 character function 3 times in the same line and you are limited to 80 characters sucks.
Contrariwise, I try to keep my code under 72 columns wide, and impose a hard limit at 80. Long lines are hard to read, no matter what screen they're on.
You'd need to make a case of which value, and why, and why it is better, so that the terminals can standardize on it.
I actually like the limitation, because it makes me use more enters, so that the information ends up not within one line but in multiple. Which mans more lines (and LOC) but better readability.
I guess a good comparison is Twitter's limitation on the characters. It has its pros and cons.
Point taken that it is ok to use i, x, y, z sometimes (eg. when iterating), but the notion 'a meaningless parameter that is just a variable' doesn't really exist... if it's meaningless, why are you saving it?
Only other use case I can think of is doing metaprogramming or some sort of templating where you have a variable, but might no even know what it represents, because it isn't your concern.
map transforming_function (element:rest_of_list) = transforming_function element : map transforming_function rest_of_list
...but the cost in terms of loss of brevity would far outweigh a benefit that would only accrue to complete beginners, who would be better served by comments and test cases.
A variable can be a substitute for a longer expression for which a name/description is unnecessary because the expression itself is self-explanatory. The substitution with a (essentially meaningless) short name just makes repeated use of that expression more readable. Using a long, descriptive name would defeat the point.
> You also want names to be easy to understood, therefore, longer than few letters. So, "count" instead of "cnt" or "c", in short, no abbreviations.
Yet in cars, BMW is an abbreviation. IBM is also an abbreviation, Microsoft gets abbreviated to MS, and NS to NextStep.
"Nobody" calls BMW and IBM by their full name.
Only people in IT know and/or use the abbreviation MS (which is functioning), and only people into NextStep and macOS use the abbreviation NS (also functioning).
Would you want people to spell out Bayerische Motoren Werke all the time? With or without AG? Or would you want to use the English version, Bayern Motor Works? People all around the world know the acronym BMW; it does not have to be translated. Would you want the API calls to spell out NextStep?
I feel like established abbreviations are perfectly fine, and some people/companies (entities) try to get established.
In many cases these abbreviations have officially - legally - become the organisation's full name. In Australia, for example, the Colonial Sugar Refinery, known as CSR, officially changed their name to simply CSR (and only CSR) in the 1980's, IIRC.
While I love the sound of Bavarian Driving Machines, it's a translation / transliteration (mostly the former), and doesn't add much value beyond nostalgia.
Also, in Australia, these vehicles are mostly called Beemers anyway. (I'll note that I'm not a fan of Strine vernacular.)
A small nitpick - BMW is not an acronym - it's an abbreviation or initialisation. Acronyms are pronounceable words.
"The broader sense of acronym inclusive of terms pronounced as the individual letters (such as "TNT"), is sometimes proscribed, but is the term's original and more common meaning"
"1. a word formed from the initial letters or groups of letters of words in a set phrase or series of words and pronounced as a separate word, as Wac from Women's Army Corps, OPEC from Organization of Petroleum Exporting Countries, or loran from long-range navigation.
2. a set of initials representing a name, organization, or the like, with each letter pronounced separately; an initialism."
> That isn't universally accepted as part of the definition of 'acronym'.
That's the general sentiment of this thread -- that it's not universally accepted.
I'd refer to the Oxford English dictionary, but your citation from the Merriam-Webster contains what I understand is the defining feature:
> "a word ..."
With three examples of words (ie. pronounceable strings).
The addenda of 'also: ... other things' is a bit of a cop-out. This is the distinction between a dictionary that strives to provide definition of language, versus recording popular (mis)uses.
Oh, thank you - I'd seen this listed as driving machine translation several decades ago and hadn't pursued it more, just assumed that was legit.
Reviewing on Wikipedia I see that:
"Bayerische Motoren Werke [...] This name is grammatically incorrect (in German, compound words must not contain spaces) ..." which is reassuring, given my own general bewilderment with German grammar.
Language is 1) defined by its speakers, and 2) should be practical. It's just silly to invent a new word, "initialism", to distinguish between things you pronounce as a word and things you pronounce letter-by-letter. "NASA" and "FBI" are the same type of thing in most people's heads; there's no need to have a separate, awkward word for the second thing.
It’s not a newly invented word. Google books shows both “initialism” and “acronym” to have been in use since the 1800s. Saying we shouldn’t have more specific words because many people don’t know their meaning doesn’t make a lot of sense to me.
> ... the first known published use of the term in English [is] from 1940
That published use is as follows [1]:
> Pee-gee-enn. It's an acronym [Ger. Akronym], that's what it is. That's what they call words made up of initials.
In other words, the very first recorded use we have of the word "acronym" is actually what some people insist on calling an initialism. I don't know who, afterwards, decided that "acronym" had to mean that it had to be pronouncable, or why, but I didn't vote for them.
> Saying we shouldn’t have more specific words because many people don’t know their meaning doesn’t make a lot of sense to me.
I didn't say it was because people didn't know their meaning; I said it was because as far as most people are concerned, they're the same thing. I know what "initialism" means, but I choose not to use it, because as far as I'm concerned "NASA" and "FBI" are fundamentally the same thing. It's a waste of brain cells to figure out when to say "acronym" vs "initialism".
As an example where I think such a distinction is important, I do consistently write "MiB" when I'm talking about 2^20 bits. I only saw it the first time maybe 10 years ago, but it immediately seemed to be to be both practical and useful to make that distinction.
On the other hand, I never correct or ask clarification of people who use "MB", unless the difference becomes important. (Nor do I say "mebibyte", which is the proposed pronunciation of "MiB", because it's impossible to pronounce fluently.)
1. I'm not 100% convinced language is, or more importantly should be, defined by the speakers -- or rather be defined indiscriminately by all speakers, regardless of their qualifications or credentials. It tends to result in a convergence of similar words, weakening the strength of language and variety of expression available for people who understand the (original) distinctions.
2. I'm an English language speaker (and writer) and you seem to be discounting my right to define language. Or just to maintain the definition of certain words because they contradict a weakened but popular & recent redefinition.
3. I'm not advocating initialism - it's not a word I recall ever using. But I'm not sure it's reasonable to claim that it's silly to invent new words to describe new things. I'd advocate abbreviation for an abbreviation you can't pronounce as a word, and acronym for an abbreviation you can.
> I'm an English language speaker (and writer) and you seem to be discounting my right to define language.
Fair enough -- you have a vote; but when you "vote" for something from a minority usage point of view, you should make it clear that you are advocating for minority usage, and why. What you did instead was to assert that the "right" way to use the word was X, when in fact the initial usage was Y, and most people still use it as Y.
I don't object to people thinking carefully about how a language should work and then advocating for it; that's what I do myself. Nor do I object to correcting common "minority" usages that I think are going in the wrong direction. But a lot of people advocate changes which are more "pure" but are clunky and unhelpful.
For example:
* Using 'they' as a singular of unknown gender; i.e., "I have an appointment with Dr. Smith; when will they be free?" English has need for such a usage; 'they' is simple and understandable; and it's been in use since the 1400s. I'm a fan.
* Using "literally" as a meaningless intensifier; i,e., "My head literally exploded." I strongly object to this usage, and I will continue to object to it as long as it's practical to do so, even if I become a minority. The reason is that we already have hundreds of intensifiers, but we don't have very many ways to say, "I am not exaggerating or speaking metaphorically, this actually happened."
* Switching from "negative agreement" to "double negative == positive". In French, to say you've never done something, you say "Je n'ai jamais faire rien", which literally translated would be "I not have never done nothing". But it's not called a "triple negative", it's called "agreement": if any part of the sentence is negative, the whole sentence has to have negative forms. If you go back to Henry VIII's time, that was the officially correct way to say things in English too. but at some point, some people came in and said, "Well, if we make all negatives contradict the other negative, we can say things like 'It's not nothing.'" Then educated people got rid of agreement, and started telling less educated people, who were speaking the same way English had been spoken for hundreds of years, that they were speaking English "wrong". I think the new way is better, but I think it was kind of a jerk move to change it.
> I'm not advocating initialism - it's not a word I recall ever using. But I'm not sure it's reasonable to claim that it's silly to invent new words to describe new things. I'd advocate abbreviation for an abbreviation you can't pronounce as a word, and acronym for an abbreviation you can.
I didn't say it's silly to invent new words to describe new things. I'm saying that for most people, NASA and FBI are not different things. FBI is a word pronounced "effbiyaye". If people really thought of FBI and NASA as different things, then it would be easier to give them different words.
On the other hand, when people hear "abbreviation", they think more like "st" for street (or saint), "dr" for doctor, and so on. FBI is more like NASA than "st" or "dr". So it makes sense to call FBI and NASA by the same word.
If you personally think that making that distinction is useful, then by all means do so in your own writing. And if you think it's important for people in general to make that distinction, then go ahead and advocate for it. I'll continue to advocate against it, and people on the whole will decide. :-)
You seem to be claiming two somewhat contradictory positions:
1. that I can not conveniently claim acronyms should be words and abbreviations are a superset that also includes non-words -- because the alleged original meaning of acronym was as a synonym for abbreviation, and
2. the initial meaning of 'literal' as something that was strictly true, but which has since moved via common usage to simply be yet another synonym for metaphorically, but you don't want it to change.
FWIW I also rail against literally being used for things that aren't literal, I don't dislike 'not unlike' and similar despite Orwell's (et al) protestations, I'm happy to co-opt 'they' as a third person personal pronoun (or restructure sentences to avoid needing to uncomfortably alternate and track he and she), I vehemently defend the difference between alternate and alternative, myriad is not a collective noun (don't precede with an article, or follow with a preposition), I never use decimate as a synonym for devastate, etc.
I suspect most misuses are from people who've heard or seen a word they weren't familiar with, failed to understand or research the meaning or part of speech, believe using it will imbue some much needed gravitas to their communication, and then expect the world to adopt their befuddlement.
As we seem to agree, the ultimate outcome of all this is a weakened language for sophisticated users.
When I need to describe an abbreviation that's pronounceable, I evidently now need to call it an abbreviation that's pronounceable. This is a retrograde step for me, despite the word 'abbreviation' already being appropriate, well known, and understood by world+dog.
> On the other hand, when people hear "abbreviation", they think more like "st" for street (or saint), "dr" for doctor ...
How comprehensive was the survey group behind this claim?
You seem to have missed the main point I was trying to make:
"Vote" for a language which is useful and practical.
I specifically said that if you think it's useful to say that NASA is an acronym but FBI isn't, then go ahead and do so. Just be prepared to give a justification of why you think it's better.
"That was the original meaning" isn't valid, because it wasn't the original meaning. "That's what all the dictionaries say" is a weak argument. I didn't elect them and I don't agree with their decision.
Indeed. It is all about the produced sound. There's a format for that, but I'm not accustomed to it, so say phonetically there's "Ef Bee Eye". You could call the organization "Efbee Eye" or whatever, but why would you? "FBI" and "Feds" both work; they're both well accepted as it is.
>You want names to be short, so you easily write and read them.
Hmm, I don't think short names are easier to write or read than a "medium length" ones, at least not for me. I mean naming something with a 30 character string is another matter, but names composed of a few words are not getting in my way during development/review.
I don't understand why would anyone find underscores ugly. Underscores are basically spaces. And we use spaces in our language to separate words. May be text editors should draw underscores with more subtle way?
Underscores are difficult to distinguish from underlining. That's just one issue.
Underscores_make_full_highlighting_easy
Dashes-make-single-highlighting-easy
It's also a use case thing. Double click on each sentence and note the behavior. It depends on which one you want. We use snake case in our urls because you can copy something from the documentation and easily highlight a portion to change.
Does any language use underscores? They seem like a purely technical thing to me. In a sentence you are certainly correct the - is much better. But as for the name of something in code, I would personally prefer _.
Why does it matter what things are called if the name of the thing might be a lie anyway? I'm going to have to check what it does anyway!
I've adopted what I call the square rule (I've never heard it called anything else): The length of the name is the inverse of the square of the extent, and the frequency of its use.
Thusly, a short name like "i" might be acceptable if the number of source code bytes between all the users of the variable are small, such as:
or if the variable is used almost everywhere in the program: I might have:
register int*G asm("r12");
and be okay with it if nearly every function in my program is using G in some way. If you've heard of a similar rule to "huffman-code" your variable names, you can imagine I've simply adopted a dictionary selection strategy.
That works for me, but in a large program it breaks down, because a large program may have multiple names for the same operation, and with multiple programmers (even following this rule) it may be difficult to predict the names chosen by other people on the team. That leads to code bloat, because programmers will often invent similar utilities (but for different purposes) with different names.
I'm working with a guy at the moment who is fastidious about naming. He's the naming czar in this project, and almost nearly every function in this application has had its name blessed by him, so they're unusually consistent, to the point whilst I can't quite predict what something might have been called when searching to see if someone has already written a function I might like to use, I can ask him what something should be called and if it exists it will certainly have that name.
That's cool! That's also a bit of a new/interesting experience for me, and even though I see some value in it, it doesn't scale, and I don't know how to replicate it. I would see value in a book that can teach how to name things that need good names, that team members who can carefully follow the strategy can end up with consistent names so we can find each others hard work faster, so I hope this book (the author is describing) addresses this point, instead of the inverse: crappo-drivel about predicting a functions' (or definitions') implementation from its name, something I see a lot of bloggers wax on about, but has negative value to me.
> Why does it matter what things are called if the name of the thing might be a lie anyway?
It matters because the names you choose signal your intent.
As Knuth put it: "Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do."
A line of code is going to be read hundreds or thousands of times more often than it is written. The more someone has to scan around to discover the purpose or intent of something, the harder/slower your code is to navigate. And this magnifies by the thousands of times it gets read by humans.
Code has UX, just like all human interfaces have UX. We've already discovered that better UX is a good thing. Code is just another user interface to optimize for discovery.
Now I don't see names signalling his intent. What I do see is that the code is arranged carefully into a narrative with the following property: code you want to read next is either immediately or before the code that uses it (or even just that piece of functionality). Little care seems to be given to what things are called directly -- almost the exact opposite of what you're suggesting.
A little unfair to drop folks in the middle of the module. If you picked up War and Peace in Book 2, Chapter 14, you'd probably be pretty confused too.
I realize the program as a whole suffers from similar faults, but let's try to be fair.
Edit: Ok, I skimmed most of both files, and my initial impression seems to hold: there are short names, some are abbreviations, some are acronyms, but I didn't see (could have missed it) any "meaningless" name (ie. one that wouldn't have an expanded form of one or more words).
But it's kind of beside the point with Knuth's work. Of course he uses short names: he just spent 3 pages of (carefully edited and typeset!) text to hammer its meaning into your mind. There's no way for you to misunderstand, or not understand, what the symbol signifies - so what does it matter what symbol it is, exactly? [EDIT2: it matters when typing]
If you (anyone reading this, I mean) want to use these as an excuse for using meaningless and short names as identifiers, remember: these are ok if bundled with 80 lines of narrative explaining them...
Of course these are "ok", but it's not because there's "80 lines of narrative". Sometimes there's only one or two. Sometimes there's none.
What makes this "ok" is that it's clear that the author intends you to read all of it. Code. Literature. Everything.
I don't know why, but for some reason, a lot of people think it's okay to "scan" or "skim" code. To just not read it. They wouldn't think of doing this to a good novel, but they'll do this to code.
Literate programs trick you into reading a novel with bits of code in-between, such that you can digest the code and non-code parts at the same time really aiming to cement both your (the reader's) understanding, as well as the author (the programmer's) understanding†.
But listen, we can choose to actually read code too. It's hard. Much harder than just "scanning" it, but we can do it. And with some care and taste, that code can actually be as good as "80 lines of narrative".
[†]: Mathematics has been doing this for years because it's often really hard to understand complex things from the notation alone, especially when you have to invent a new notation just to discuss this new thing you're thinking about!
Well, the "80 lines" was supposed to be a joke, guess it failed... Anyway:
> And with some care and taste, that code can actually be as good as
That's true. Also because modern languages are more flexible than the ones in the 80s - probably, I wasn't around back then, but I remember from learning C that there was "old style" where all variables had to be declared at the beginning of the function, and that "new style" (second half of 90s?) was to declare them at the point of use. My guess would be that this and other similar limitations were the reason for writing CWEB. The order and flow of the presentation is very important to Knuth, so he wrote a tool which allowed him the freedom of putting text and code in the way he wanted.
Modern languages are in general flexible enough to make this a non-issue, as the presentation can be safely included in the source, and you have much freedom in structuring (ordering) the code, too. CoffeeScript is one example of "literate programming in the modern world".
That being said, I think you greatly underestimate how much care is needed to write code like this. I'd guess that not many professional programmers could do this - it's that hard. But yeah, beautiful when executed well.
> As Knuth put it: "Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do."
I've never heard that one before but it's brilliant. That second sentence should be the opening sentence of every introductory programming course.
Yes that's right, 1mb of source code text, all in one file.
If you haven't had the pleasure of a well-considered literate program, it might be funny to hear that I'd actually prefer this to a lot of shit I have had to deal with in my life...
A well-written literate program is a joy to work with. To be able to genuinely understand a complex program's design by reading well-written prose which forms part of the source code. Literally reading code like a book, finding that it effectively has a plot and characters with understandable motivations, properly introduced and their places and relationships clearly understood. Done right, it can work so well.
The only software I ever worked on in which the customer never reported a single bug was written entirely in literate code.
The software I work on now is so much at the other end of the scale that sometimes when the customer reports something, there is a signficant period of investigation before deciding if it's a bug or if that's how it's meant to work.
BTW, that .web file is not meant to be read directly (even Knuth doesn't read that file, except to make edits). The form in which it supposed to be read, and the form in which it was published as a book (though with some added typographical/indexing niceties) is the "woven" form, e.g. what you can find here: http://texdoc.net/texmf-dist/doc/generic/knuth/tex/tex.pdf
I found the CleanCode book suggestions good enough for naming conventions:
Variable name length should be proportional to its scope. Only used in the next three lines? "i" is good enough. Is it a public field? Then its name should be long enough to be descriptive.
Functions are somewhat the inverse of variables - private functions called once or twice should have long descriptive names, public functions / api calls should be short descriptive names. This way I can always tell by glance what goes on under the hood if I ever have to peek.
Contrary to parent comment I found it absolutely unacceptable to call a function "asm". A few more characters costs literally nothing and it helps communicate intent to other programmers or future self. Even if the name itself become a lie the intent will remain true and will tell stories about what the original tought process was.
Widely used libraries have one more constraint, in that they will always be used a lot, but they'll never be the most used things on any code base.
As a consequence, they shouldn't use very short names. They should let the 1-3 letter names available for local code. (But there are exceptions, of course. There always are.)
You misunderstood the parent code snippet, even if your statement will still stand. "asm" is a GCC intrinsic for inline assembly code. The name he was pointing to was "G" - that is, in the entire program, the variable G is used to mean a pointer to processor register r12 I believe.
Yeah I misunderstood it. I never wrote a single inline assembly code in C in my life so that probably flew over my head but I hope my general message is clear: don't use less letter than whats needed to be understandable and descriptive.
If every C programmer thinks the same when he sees 'asm' then its great. If you have to go into the function body to find out "what the fuck is 'asm'" then its definetly not and your function name is bad and you should feel bad.
Thats the message.
Like... 'eval' instead of 'evaluate' is probably fine as everyone understands it (though I would vote for the latter). 'evaluate_code' is just additional noise without entropy.
'umount' or 'passwd' or 'usr' gets a sad head shake from me every time. Or function names with numbering in it. These things are just terrible.
> Variable name length should be proportional to its scope.
I remember the rule from CC, and I kinda like it. But there are obvious exceptions to that. There are things like logging or printing in the global scope that one would die for to have short names.
Also if you have an object with many fields that you need to access. Then it is more convenient to give it a short name, to make the code more readable.
So parent's suggestion, to have length of the name inversely proportional to its frequency, is also a good point. The two conventions unfortunately sometimes contradict.
I agree and these are definetly just guides not hard rules to follow. What I'm really against is using a short name which don't convey any meaning.
For example 'getRtw' - which is a great shorthand for something we may never know until we go and find out. That is unacceptable naming anywhere regardless of scope, function, whatever. Use short but meaningful, pronouncable words as names and don't left out random characters from it (like usr instead of user) because thats just silly.
Replacing all identifier names with random strings (perhaps excluding built-ins and third-party dependencies), and then having an outsider try and understand what the program does in under N minutes, could be such an interesting litmus test of how well a program is organized and structured beyond naming.
(Which is not to say naming is unimportant, of course.)
If we can't agree what something means and keep these things up to date our software will become meaningless junk. There is agreement about short index names.
I prefer to name things with intent and rename them when their usage changes.
> I've adopted what I call the square rule (I've never heard it called anything else): The length of the name is the inverse of the square of the extent, and the frequency of its use.
See Gerrand’s rule of thumb
> The greater the distance between a name's declaration and its uses, the longer the name should be.
I haven't looked much if this exists, but a name generator script would be very handy. Ask for a couple of parameters, what does it do, what does it affect, etc. And then it spits out a name. Would be a great ide extension and could have a config file that checks into the source code to help keep things consistent.
I'm aware of https://hoogle.haskell.org/ which is kindof like that: You give it a type description and it tells you all the functions that have that type. Unfortunately, it's not actually that useful in my experience.
I once saw a sublime text plugin that someone could insert a description of a function and it'd automatically pull in code snippets from stackoverflow. It was cute, but I have serious reservations for some of the code I've seen in stackoverflow.
I imagine someone somewhere might have tried hooking up GPT-2 (or something) to a JIRA database of user stories and the diffs, and I'd be curious to know how that works.
I think what would be more handy is a standardization of how APIs should be written across many different domains, to make modules more interoperable.
The result of conceptualizing and abstracting different domains is in as much of a Wild West as it’s ever going to be today.
This reminds me I wanted to research about the theory of marketplaces to understand better how can we improve the market of reusable software components. By that I mean improving the process that we actually use to find and use or create and distribute reusable software components.
You are seriously suggesting breaking my coding workflow, to open a popup just to give me a half-assed suggestion I will probably dismiss anyways? Visual studio wants your location
I bet our employers and especially our customers also don't care which programming languages we use, or which frameworks. But we, developers, care. That's enough.
IMO talking about "better naming" is missing the underlying problem.
Every real world software project is a mess of unstructured identifiers being created and managed in ad hoc ways. There are thousands of names whose components are actually in a relationship with each other — FooBars and CustomerSpecificFooBarXYZMutators and FrameworkZProjectABCFooBarXYZMutatorFieldValidators etc ad infinitum — but nothing lets you discover and manage those encoded relationships.
Tools like autocomplete are simply usability patches to hide this inherent lack of structure in flat names.
Maybe you remember GOTO?
Imagine if the proposed solution to 1970s BASIC's flow control woes had been:
"We really need to get better at managing our line numbers. Let's enforce strict rules about what the numbers mean, and build autocomplete IDEs that can tell you exactly what's at line 145530!"
This where large-scale software engineering is currently with naming. Any amount of org-level convention and tooling can't make up for the inherent flatness of identifiers in our current crop of programming languages.
Once identifiers become structured instead of plain strings, it will have the nice side effect that a few of the industry's most ridiculous time-waste problems like snake_case vs camelCase in APIs will simply go away.
It's not a complete solution but most popular OO languages have some concept of modules or packages which provide separate namespaces used for grouping related classes.
I feel namespaces imposes the wrong structure. It’s just a tree where the actual problem is mixing in multiple levels of concepts and describing their relationships. (Sort of like OO inheritance vs. composition — or maybe a closer analogy would be file system vs. database.)
Remains to be invented, I guess? It's certainly a difficult problem, and any solution will be going against 70 years of convention of programs as plain text streams. I don't think we're going to be stuck here forever though.
If we want to be communicate effectively, it's important to think carefully about the words we use.
Writing code serves two purposes. On one hand we're instructing a machine to carry out the operations needed to achieve our aim; but on the other, we're helping our peers understand how we got there.
There usually aren't many technical restrictions in place when naming things in code; we have a lot of freedom. Based on this freedom, I think guidance, strategy and discussion re. establishing conventions would definitely be useful.
I agree, and I suppose a lot of it is communication 101. Part of that is knowing your audience. You'd need to ask yourself a bunch of questions ("and you want to have them answered immediately!!").
* Who is your audience?
* Who do you want to be your audience?
* Are they technical or not?
* Are they familiar with the content?
* Are they native English speakers?
* Will non-native English speakers understand the communication?
I'm by no means an expert on this subject, so I'm unsure this list is complete.
I think these are all good points when it comes to writing technical documentation, but with naming things in code there are a different set of problems.
You can't hone your approach for a specific type of audience, because you can't make assumptions about who'll be reading it.
I think we can assume they're technical, and that they're proficient in the language the code is written in. Maybe we can't really assume they're familiar with the project, they could be new to it; but I think it's fair to say they're willing to be invested enough to become familiar.
--
The way we name 'things' in code, allows the reader to infer more about that 'things' place, contextually, within a larger structure.
* How can I indicate what this structure contains?
* How can I show why I have chosen this approach?
* How can I show how this section of code relates to the larger code base?
My default audience is myself before I started working on this problem. I assume general and technical knowledge, but little domain-specific knowledge and no knowledge of how the solution works.
Sometimes I'll target specific team members whose knowledge doesn't overlap mine well. Or I'll drop URLs for background info in block comments.
I can relate to this. Especially being new to programming leaves one with so many options to name things. Just recently I wrote something about naming conventions in JavaScript [0], but this is only syntax related common sense and not applicable for any other language (I guess). So it would be great to have a guide that doesn't only go into the syntax, but also the semantics (boolean: open -> isOpen). Thanks for putting this together!
The word is not native to 8859/latin1, and there are several different transliterations in common use (afaict depending on region). Kebap is one of them.
See also: pita/pide (the bread the keba{b,p} comes in)
I personally can’t wait to move past the expected snarks to the known quotes on this issue (already added in comments). I commend any effort on the subject.
Hi, I'm the author. It's exciting to see this on HN! Feedback about this topic (here and elsewhere) has been immensely helpful, so please don't hesitate to let me know your thoughts in a comment here or via email [0].
Glad that this topic is important to you, too! I should be able to follow up on your comment soon. Because the article is long, I want to make sure I have time to give it a thorough read.
i know, this was a tongue-firmly-in-cheek kind of comment, but on the off by one chance that you are serious, look no further than: 'A Primer on Memory Consistency and Cache Coherence' (https://www.amazon.com/gp/product/1608455645/)
and ofcourse, while you are at it, you might want to check out 'UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching' as well, it also is pretty good, but with a broader focus (https://www.amazon.com/dp/0201633388)
The off-by-one extension to The Joke annoys me to no end as obnoxious and unnecessary.
But, the church of "At Most Once Delivery" is legit. If it's important, they'll call again.
The network is unreliable. It's not a happy fact. But, it's real. Pretending it's not real only leads to sadness and frustration. Accepting it for what it is leads to the revelation that you don't actually need everything to be perfect all of the time. And, greatness follows.
I spent a lot of time on it and about halfway through the process decided it needed to be split into two parts. The second part is still in draft status.
Even though the article is long, it's very specific. I left some things out for sure. A book on naming makes sense, if for no other reason than we need to be having these conversations.
Nice! You'd asked for my thoughts on this article [0]. Choosing the correction level of abstraction is an important part of naming, so I appreciate that the article focuses on it. (In case anyone is curious, this topic is discussed in the book, too.)
Walking through the Abstraction Ladder with an example is a useful approach here. I'm curious if the same takeaways could be achieved in fewer words (it looks like the article is currently ~3,000 words). I've personally found the Pyramid Principle [1] to be a helpful starting point for determining which points I'd like to make within a piece of writing and then structuring the content around those, which may be applicable here, too.
Thanks for reading and providing feedback. Yes, it definitely could've been shorter, but everything in it is intentional. Many longer pieces suffer from lack of editing, which was definitely not the case here. Looking forward to your book!
I remember Peter Hilton giving a talk[0] and then speaking on a podcast[1] on the subject of naming. I thought at first it was him who was writing the book. Surprised that it wasn't :-)
Naming is a constantly changing optimization problem. Fighting the mostly opposing forces in programming:
- Productivity (how quickly you can write out functions, variables etc..)
- Readability (how quickly can a human interpret the meaning of the code)
Both of these dimensions of the "naming problem" refer to the human side of coding.
If you have an empathetic perspective for future humans who read your code, you will tend to name things better... which makes the code easier to read, maintain... which makes the code better.
I wrote an article on this last year, which scratches the surface. My conclusion was that a good name is whatever the team thinks is a good name: you cannot write a set of rules that defines good names.
I agree with the author of the post saying that naming is poorly understood. That isn't to say that names are poor, it's just that the principles and importance of names is often not understood. What's the difference between a user-facing mass-market brand name versus package or component names? Why can I happily talk to my team about Drupal and everyone from the PM down to the intern are on board, but mention it to even the more savvy of end users and they glaze over? Why can't I just give a list of packages from the apt repository to my father and expect him to crack on with it in the same way I would if I put him in front of the Apple App store or Play store?
I'm fairly sure this book is going to be about naming things within codebases or within the technical community, however I still find myself disagreeing with his list of principles in the next page over.
> 1. Consistency - Each concept should be represented by a single, unique name.
Agree and disagree. I agree that the same concept in the same context with the same audience will need a consistent name so that there is no confusion, but names are used to convey extra bits of information. Consider "headache tablet" vs "Paracetamol" vs "N-acetyl-para-aminophenol". Different audiences, different needs, different information being conveyed. Arguably the same component for a different concept, but even so it breaks the notion of consistency. In Mathematics we use different notation for the same concepts sometimes in order for our ideas to be expressed more succinctly or for our workings/thinking to be clearer. The same is true in tech.
The secret isn't to name sparingly, it is to name well.
> 2. Understandability - A name should describe the concept it represents.
This is good in principle, but one concept could have many applications. I think sometimes we are limited in how we think about things merely by how they're named. As noted above, names can have certain assumptions baked into them which, while subtle, can block other forms of thinking. Even taking something like 'Object' from OOP can be misleading. You don't always have an object for a solid thing, a well-defined business concept/entity etc. The object itself only makes sense to those working at the same level of abstraction as the code which may only be the developers of that specific application. The term 'object' itself, then, becomes only meaningful as a programming concept, it doesn't actually describe what the thing is other than "a collection of stuff with things you can do to it attached".
> 3. Specificity - A name shouldn’t be overly vague or overly specific.
I've touched on this above, but in this specific case we're aiming for a middle of the road please-everyone-but-no-one approach where the name is neither descriptive or catchy enough for people to remember, specific enough for people to find useful in practice or intuitive enough for people to build up mental models around.
> 4. Brevity - A name should be neither overly short nor overly long.
If you make it too short then everyone will only be able to name your concept with qualifiers. If you make it too long then people will abbreviate so that it is no longer unique. If you have multiple names for multiple purposes you break the 'single consistent' name principle above. Long names have uses. Short names have uses too.
> 5. Searchability - A name should be easily found across code, documentation, and other resources.
I like this. I think every project/concept needs to have at least one name that is specific and unique enough that you can use it to find exactly what you need to. I do, however, think that the name is only part of this. You also need unique combinations of names/concepts/verbs in order for you to find the specific thing that you need.
> 6. Pronounceability - A name should be easy to use in common speech.
Again, depends on the purpose. (pentacyclo[4.4.0.02,5.03,8.04,7]decane) is technically pronounceable but cumbersome in casual conversation. It is also unique and descriptive. Everything has its place.
> 7. Austerity - A name should not be clever or rely on temporary concepts.
Sometimes these are good, sometimes they turn sour. I agree that the Gnu Image Manipulation Program should have a more savoury name if it genuinely wants to serve the needs of a mass audience. I also like that `less` is `more` - a joke that means that the `less` command doesn't really describe its function or give the user any clue about its place in the ecosystem without using it or looking it up.
So yes, I think ultimately some of these are "no, that won't work" and others are "it depends". A nice, albeit somewhat cryptic, explanation of names is discussed at various points in Patrick Rothfuss' Kingkiller Chronicle. He also has some interesting blogs on the topic of naming if you can hunt them down.
Thanks for the thorough feedback! I really appreciate specific feedback like this. (I'm the author.)
I agree with many of these points, and the content of the book has more alignment with your perspective than the brief list of principles may suggest.
Many of these principles (and their names) still seem imperfect to me, but I've been struggling to find better ones. I'll take a look at The Kingkiller Chronicle; if you have other thoughts on how to improve the principles apart from what you've mentioned above, please don't hesitate to let me know.
>I agree with many of these points, and the content of the book has more alignment with your perspective than the brief list of principles may suggest.
Interesting! I shall keep reading in that case! Will let you know if I have any further feedback.
> I'll take a look at The Kingkiller Chronicle
The blog posts that touch on naming are here [1] but there are definitely a lot of posts just related to baby names there. He also talks about it in his podcast with Cards Against Humanity's Max Temkin [2]
You want names to be short, so you easily write and read them. Especially if you use them a lot, it's useful to use abbreviations, like x, e, i, z.
You also want names to be easy to understood, therefore, longer than few letters. So, "count" instead of "cnt" or "c", in short, no abbreviations.
You want names not to clash. So every name should be a unique 64-character long identifier, as far as distant from anything else as possible. However, they should also be optimized for the tree search when using completion.
You want names to describe similar things with similar names. In particular, my pet peeve, how to name objects that are "essentially the same thing" but only different structure so I could better manipulate them, like converting list of tuples to a dictionary? From purely domain point of view, they should not even have different types! And did you know that every Monad is an Applicative?
Should the name reflect the result only or also the path that was taken to get to it - "customerList" or "customerListFiltered"? Or perhaps just "list", because the function is not specific to customers. It's local context versus global consistency.
There are minor problems as well. Underscore_case looks ugly, dash-case is mostly not supported, camelCase is just weird when you want to have anotherCamel (now strangely upper-cased), and CapitalCase looks ugly with acronyms. And should we put adjectives in front or at the back? And why are the elements of EMarble called RED, GREEN and BLUE?