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.
https://github.com/wkoszek/cweb/blob/master/cweave.w#L382
https://github.com/wkoszek/cweb/blob/master/examples/oemacs....
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.
I realize the program as a whole suffers from similar faults, but let's try to be fair.
https://github.com/wkoszek/cweb/blob/master/examples/oemacs....
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...
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!
> 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.
I've never heard that one before but it's brilliant. That second sentence should be the opening sentence of every introductory programming course.
http://anorien.csc.warwick.ac.uk/mirrors/CTAN/systems/knuth/...
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...
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.
Reading someone's code feels like peering into another persons head, trying to imagine both what they must have been imagining.
Sometimes that can be a real scary thing, but for those of us who like a good haunted house, it can be a real treat too.
The Harold Abelson version — "Programs must be written for people to read, and only incidentally for machines to execute."
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.
You can take your snark up with GCC, and leave me out of it:
https://gcc.gnu.org/onlinedocs/gcc/Global-Register-Variables...
On the other hand their criticism contradicts their earlier point about widely used public/stdlib function names best having short names.
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.)
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.
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.
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.
If you think naming doesn't matter, why should I read the rest of your opinions on the subject of naming?
Imagine a program where all the keywords and identifiers have been replaced with randomly generated strings.
(Which is not to say naming is unimportant, of course.)
I prefer to name things with intent and rename them when their usage changes.
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'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.
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.
{int k=0,i=0;for(;i<500;++i)if(do_something(i))++k;return k;}
- your employer - your customers
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: 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.