What science says about naming in programming
felienne.com
felienne.com
Global variables (if any) are long explicit phrases while inner loop variables can be a single letter.
Without taking scope into account the naming guidelines become dogmatic and impractical trivia.
EDIT: wording
It's much more readable and you're less likely to get name clashes with other functions (r could be lots of things (even in the same file) - render, record, row, red, right)
for (let thing of things) {...} for (let particularThing of things)
for (let th of thigns)I actually really like reading/writing code that uses really small variable names but are still very obvious given it's context (usually never acronyms though, I despise those). I'd always rather working with something small like p1 rather than something very descriptive like sceneOffsetPoint1, especially if I can read the code above it that shows it being assigned based from the scene center point: let p1 = scene.center + Point(2,3);
In particular the most likely explanation for correlation between bad names and bad code is unskilled or inexperienced programmers. This needs to be controlled for.
My personal observation is that well-factored code can use shorter identifiers because it deals with fewer concerns. Long identifiers frequently indicate muddy thinking that mixes concepts, where the identifiers are burdened with disambiguation.
Further, in languages with particularly verbose identifiers (Java especially), it can get hard to see the wood for the trees: the density of text obscures code and data flow in the program. There's a similar argument to be made about the tradeoff between symbolic operators and textual operators: the more frequently they're used in a domain, the better they're represented by a symbol. Symbols, of course, are especially short identifiers.
Regarding the verbose identifiers, I recall the first time I started looking at Objective C (and NextStep I believe) while attempting to get into iPhone/iOS development. I couldn't believe what I was seeing. IIRC there were function names that were damn near 80 characters long. I played around with it and built some simple iphone apps, but I just couldn't take it.
Totally disagree with this assertion: Laziness and two fingered typing are to blame.
Naming is one of the hardest things to get right, I often have to comment on it in code reviews. Long names are usually more lazy than concise ones. The other problem is naming things more specifically than necessary, obscuring genericity of functions.
This is not an easy problem to solve. For every "easy" example of a good name, one readily encounters an easy counterexample that renders the name ambiguous or unfit for a particular purpose.
Names must necessarily include context to be meaningful. If "name" is an unambiguous identifier in your scope and it's obvious what it does, great! Don't fix what isn't broken. But when you catch ambiguity or uncertainty, revisit the code, so future developers have an easier time understanding what you meant.
And this digs out a tangential problem - that often, "name" is as specific as you can get (or at least as specific as you should get) - http://www.kalzumeus.com/2010/06/17/falsehoods-programmers-b....
Doctor, it hurts when ...
Also, notice how R, G, and B have a very clear meaning when put near "color"? Context is a thing our brain manages very well.
(let ((copy (copy-list list)))
(list copy 'copy 'let))
(but yes, you are right)
What has bitten me many times is accidentally overwriting a builtin function like max or len in python and then scratching my head about the strange errors that result from this.
The requirements which drive the preference for either are all valid. I, the designer, have simply taken both requirements and integrated them. Of course, requirements like, "I want to use list as a variable name without shadowing the lisp function" directly conflicts with "I want to reference functions and variables the same way without function or funcall". However the conflict can be confined down to the argument list of an individual form. I.e. "Sure, you can have both, just not in the argument list of the same form."
When you're inside a function, dealing with very limited scoped variables, people get that.
People also 'get' attributes of classes and can grasp that context.
You know what's rational - that the 'length' of an array is just called 'length' :)
Anything else would be missing the point.
I have learned over many years that longer, highly readable and descriptive names make life extremely easier in the long run, at the expense of a few extra characters to type.
For example, in the case of "name" there are typically many different things that need a "name" in the same context. First name, last name, etc. "name" by itself (and other short names) is honestly asking for lots of headaches in the long run.
If you write SQL, you can disambiguate by table name prefix. If you iterate over result sets for example in python, you can easily be more specific on tuple destructuring time ("for personName, carName in ...").
When defining a table "Person", I consider it bad style to prefix all column names with "person". Btw this overzealous disambiguation falls flat as soon you do a self-join.
In real code, it's unwise to expect the reader to study context just to parse a name.
Is it "first name", "last name" or "full name"?
Is it a person's full name? legal name? first name? last name? nick name? desired call name? a company name? the name (alias) of the stored address?
Following this line of thinking, communication is impossible because everything is ambiguous.
And making everything as ambiguous as possible makes communication easier… how?
http://www.kalzumeus.com/2010/06/17/falsehoods-programmers-b...
If you're not you're definitely doing something wrong.
> (as a property of a person)
The original comment does not specify that it's "a property of a person". It could be a company, it could be a non-specific delivery address, etc...
I will now end my concern about being downvoted and get a life. The discussion culture in this thread is mad.
Btw humans also have many names, depending on context. You might have had funny nicknames in your childhood, your friends speak to you by your first name, other might speak to you by your last name, others might call you "darling" etc... likewise it's also not totally uncommon to speak to babies by the handle "Baby", like "how are you doing Baby?".
Try to open raw html/css instead of using browser to view modern website. Hard to get the picture? Yeah, and that's where we are in programming today.
I'm too busy and too single to make prototype on my own (and more related ideas on top of that in thoughts.txt). I've posted this in forum comments for years, and sometimes got critics that made me temporarily think it is just another view on existing techniques (as of company-wide, not person-wide). Now I run the company and this got only more demand.
Honestly, maybe I'm just doing existing things wrong, idk.
https://www.microsoft.com/en-us/research/publication/the-dea...
http://www.intentsoft.com/us/ <-- in "stealth mode" for 10 years!
- automatic refactors in Java IDEs, especially "rename" - they understand what you mean by "this variable" or "this function", at least most of the time
- Paredit mode in Emacs, for working with Lisp code; if you learn it, you start feeling you're actually working with a tree, and not its textual representation
A few key points that make this useful:
The documentation snippets are attached to specific methods, parameters, classes, etc - like in Javadoc or Doxygen. You don't have to wade through stuff you care about to find out about the the thing you care about (under your mouse).
DISCLAIMER: I may be wrong because my judgment of those scientific papers is based only on this article. If they do define "good" and "bad" in some meaningful way, then it's the article's fault for not pointing it out.
Wouldn't that be answered in the content of those papers?
I completely disagree, having actually worked with a lot of Java once. The language in general is extremely verbose, and the names make it worse. What saddens me is that it seems a lot of the "better naming" discussed here is the complete opposite of what I'd consider good --- I mean, one of the guidelines listed there is "Identifiers should not consist of fewer than eight characters, with the exception of {short list containing very few dictionary words}"!? In the (not Java) code I work with, the majority of identifiers, i.e. locals, are below 8 characters.
IMHO identifiers should be short and memorable, preferably even having a unique and equally memorable pronounciation (I think "strlen", given as a "flawed" identifier in one of the tables, is an example of a good one, as are the others in the C library), but it seems a lot of "modern" code is going in the opposite direction. "Long and descriptive" identifiers may seem more "friendly" at first, but I feel it gets rather tiring after having to read plenty of code in that style --- especially if many of the identifiers share a common prefix, forcing you to read through the extra noise but having to compare to ensure they're actually the same.
Thus there appears to be two distinct style groups, one with the long and verbose "dictionary word" names and traditionally represented by Java and C#. This group is spreading, I think partly because of the "ease of entry" noted above. The other group uses the short, succint, abbreviated naming traditionally represented by C, Asm, sh, awk, and most of the existing Unix conventions. (As another example to contrast sh, PowerShell is a member of the former group.) This article seems to say the former is better than the latter. I am not convinced.
Some examples for concreteness:
Former style: https://github.com/dotnet/roslyn/blob/master/src/Compilers/C...
Latter style: http://v6.cuzuco.com/v6.pdf
Edit: Another example of the latter style, from something more vaguely related to the example in the former style: https://news.ycombinator.com/item?id=5748672
Java/.NET naming verbosity is great when I'm trying to figure out what the heck I'm receiving without tracking down the class definition. The thing is, you're only willing to be that verbose because you've got autocomplete in an IDE so peeking into that long object/class/parameter name is only a click away.
The naming conventions like OncePerRequestHttpWebHandlerSecurityContextAwareInterceptorFactoryImpl are obsurd, but there's no reason you can't come to a more concise descriptive name. Frankly, if you're implementing the interface you can call it whatever you want.
On the other hand I've seen some C and JS code that I could SWEAR was run through an obfuscator before I got to it, but no, the devs refused to use more than about three letters max. This is not helpful.
Names like strlen, idx, propCnt are concise AND descriptive. I generally like to put units on things if they're some kind of measurement so I typically do stuff like intvlMS, distKM.
There's nothing wrong with being descriptive, but you can really do a disservice to those (including yourself) coming after you when it becomes very hard to fit the mental model.
Long names only becomes a problem when you're concatenating more than three words for one variable. And that's really the problem, the number of words in a variable, not its character lenght.
"propertyCount" is 6 characters longer than "propCnt". In arithmetic expressions this can easily amount to 12 or 18 characters saved.
I suggest you point out a specific example and show how you would do it in a better way.
Often people who try to write real "good" code overdo the descriptiveness and end up with technically perfectly precise names that are awful to read and remember.
Learning how to find a short, yet descriptive name for things is real hard, and very important. It's the closest I come to being a poet in my work.
The third goal I do these days is that names should be unique, if possible. When I search the project, it's best if I don't find several things with the same name.
But as a general rule I like to think that if there are many variables whose purpose is so hard to remember that their names must be super descriptive, then the problem decomposition is probably lacking.
I also think that bad decomposition is often a consequence of OO style (where concerns tend to be intermingled rather than separated because objects tend to be trashcans for everything "related" to ill-defined concepts).
A good decomposition leads to source files with distinct concepts that lend themselves to short and memorable (but not overly descriptive) names within their limited scope.
Example: The following code has a very clearly defined scope and implements a data transformation with 5 distinct concepts (cols, rows, objs, spec, database). Incidentally these show up in just about every function of the file.
https://github.com/jstimpfle/python-wsl/blob/master/wsl/wslh...
(I haven't bothered to document these concepts yet. Assuming documentation I'm convinced 4-letter variable names are just right, and repeating the documentation at every usage location is wrong).
One if the things I think Java actually does well is to provide good namespacing facilities for methods (eg. classes). That allows you to omit the type in method names.
C: strlen(x)
Java: x.length()
You apparently aren't reading my comments. The first part of the comment is specifically about that, the naming has nothing to do with C's constraint and everything to do with the community surrounding it. While I am loathe to praise WinAPI, its designers did at least demonstrate that you can use descriptive symbol names in a C API.
For new developers or developers that frequently switch between working with many different environments the short names can be a huge problem.
"strlen" is not the biggest problem; you can look up what that means, as it's well documented. The problem is much worse when short names and abbreviations are introduced ad hoc without sufficient contextual clues.
Actually bothering to document abbreviations helps. Does "proc" mean procedure, process, processor, ...?
double chnopsnrg;
double chnopsEnergy;
double carbonHydrogenNitrogenOxygenPhosphorusSulfurEnergyInKiloJoulePerGram;
double chnopsnrg; // C.H.N.O.P.S. (Carbon, Hydrogen, Nitrogen, Oxygen, Phosphorus, Sulfur) Energy in kJ/g
Also scope matters. In local scope, names can (and should) be shorter. The context is clear.
let fooBar = ... where fooBarPath = .., foorBarFile = File(fooBarPath)
let fooBar = ... where path = ..., f = File(path)
Also tooling matters. In old shells and editors without auto-completion long names of course quickly get annoying. With auto-completion and highlighting of identical words this is less problematic. On the other hand a good "go-to-definition" or "peek-documentation" feature makes short (documented) names less problematic.
I give credit to PowerShell to at least attempt to balance the two aspects, as it supports both long and short names for most things. The tooling aspect seems to have been ignored though.
Autocomplete only helps when writing, not reading; and it doesn't solve the problem of long names which have the same or similar prefices, obscuring the important differences. Long names still require reading. Here's a commmon pattern in Java and C# code:
FooBarBazIntervalFactory fooBarBazIntervalFactory = new FooBarBazIntervalFactory(...);
...
fooBarBazIntervalFactoryType = fooBarBazIntervalFactory.GetFooBarBazIntervalFactoryType();
fooBarBazIntervalFactorySize = fooBarBazIntervalFactory.GetFooBarBazIntervalFactoryType();
FooBarBazIntervalFactory fbbif = new FooBarBazIntervalFactory(...);
...
fbbifType = fbbif.type();
fbbifSize = fbbif.size();Also, I always wondered if something like this would work well: https://github.com/ankurdave/color-identifiers-mode
I've had to develop team codebases in both Eclipse and Visual Studio, and the experience was not good. Not only were the IDEs slow and buggy, but also the code (which followed the long names cult) was terrible to work with. No cohesion, no separation of concerns.
Personally, most of the time I'm happy to use vim without any plugins. Most time is not spent typing, but thinking about factorization of the program. Depending on scope I mostly use short variables. I don't expect to be able to dive into code without understanding the context -- the idea that this is possible is a misconception.
But it could very well be that the people arguing for long names do e.g. business code (where concepts might or might not be less clearly scoped and cohesive) and people arguing for short names do e.g. more algorithmic code. Without proper scope (ha!) this discussion is worthless.
The 'former style' is instantly readable code. You can see roughly what is going on and make a mental picture of it.
The 'later style' reads like Chinese. Everything requires a lot of context.
I should point out a major difference: in Java etc. you're often dealing with abstractions that have allegories in the real world, i.e. 'isEditable'. Well, that means something can be edited or not, obviously. But in C, you might be dealing with so many low-level things like memory addresses, pointers, complex data structures etc..
Software has to be maintained, and I'd personally rather have a little dose of 'tedious' than to have to decrypt some byzantine names every time I glance at some code.
I wonder what most people think about this?
Take this survey, for example. Any paper that purports to provide naming recommendations "scientifically" has to explain the Linux Kernel at least on a level footing with Eclipse or whatever other Java programs they're looking at. Otherwise it's hard to take them seriously.
In general, programming has just too many variables to be amenable to scientific analysis at this time.
a) Start with the question of how you define success. Are projects that have lots of adoption what we should be trying to emulate, even if the insides are ugly and the project just happened to be first to market, and its users don't care about how clean its code is?
b) Then there's the question of whether a study is reproducible using other codebases. Most such studies are not. The ones in OP demonstrably are not as I have hopefully proved above.
c) Software engineering studies are extremely weak at identifying or controlling for confounding variables. Most have no such discussion. The ones that have some mild discussion fail to put into context what variables they failed to account for, often the reader can come up with a new one with a few moments of thought. Given this, the conclusions they arrive at are overreaching, where good science has a tradition of modesty, of under-stating the applicability of one's conclusions.
Summary: science doesn't just happen when you want it to. A field becomes scientifically "rationalized" past a certain point in maturity, when a consensus emerges after many iterations of theory, experiment and argument between alternatives. It seems unjustifiable to say "science says" something if you can find opposing hypotheses about it in equivalent journal articles. Software engineering is early in this life cycle. I suspect it's hindered by bad axioms, such as that what we do with software today can be termed "engineering".
I've seen something similar with xUnit in C# where an Assert statement returns a value. `var single = Assert.Single(collection);` It does the assertion and returns the single item in the collection, which is awkward, but also familiar (from Linq's Single) and convenient. Here there are tradeoffs and I could care less about the dogmatic "never do this" complainers. This might break the 'Principle of Least Astonishment' the first time you see it, but after seeing it once it makes sense and is no longer surprising.
Additionally, in the case of this criteria, where there is a boolean-looking function that doesn't return boolean, it can often be quickly assumed that something more than just a boolean needed to be returned.
This also reminds of command-query separation which makes a lot of sense to follow in most cases ('get' shouldn't change state and state changing methods like 'save' shouldn't return a value). But there are going to be exceptions to this rule and there are scenarios where no matter if you return data or not you might need to know the HTTP status code, etc. Grabbing code and doing dogmatic research on it doesn't make a whole lot of sense unless a developer who really knows the code well can justify themselves and discuss the why.
The periodic table for example manages to do quite well with one or two-letter variables, which then leads to concise equations for chemistry.
Programs, on the other hand...
Why am I being downvoted for a civilized and reasonable objection which refutes the parent's claim? (of course without a counter-argument).