An important rule is missing here: variables should be named with their scope in mind. So if a variable is longer lived and has larger scope its name should be that much more descriptive because when you're looking at it the only thing that will tie the value of the variable to the context within which it can be used is its name.

So 'i' is fine for a loop control variable with a scope of five lines but totally inadequate for something expressing a larger and longer lived concept.

Ditto for function names and parameters to functions, if the function and the parameters are named properly understanding the function is trivial.

So if you write a chunk of code that exports one or more functions that is where your effort should go, that's the public interface. The reduced scope of the rest of the code should make any naming issues much more limited.

This is also why it is good to assign one person on a team to defining the interfaces between the code. That way you get consistency in naming which is a great thing to have in a codebase.

Anecdote time:

I once worked for a game programming company. One of the programmers there would name all his functions and variables for fruit and vegetables. It was his way of ensuring job security. Guess who got saddled with untangling the salad when he left the company.

cucumber(cherry, strawberry, orange);

Good luck with that...

Slide 41: "If you don't know what a thing should be called, you cannot know what it is. If you don't know what it is, you cannot sit down and write the code."

A few years ago, I programmed in Max/MSP (max4live, technically) for a while and one thing I found super-refreshing is the ease at which you could prototype and experiment your way to a solution just by not having to figure out what something should be called until you were good and ready. Ever since that time, I found that naming things is a big hindrance to evolving code from an experiment to a solution. Names get in the way until you're sure what the code is supposed to do (at which point, the above quote is true and you should be able to give it a descriptive name).

The author states:

"Most of the things programmers say about comments in code are excuses for not writing any comments at all"

This is true. Here is my excuse:

1. Follow all rules for writing good comments 2. Comment is now short, crisp and concise 3. Apply "Extract Function" refactoring, use comment as function name 4. Your comment is a compiled entity now 5. Write testcases for the function that explicitly explain corner cases and weird behavior 5. You have no comments in the code any more

This rule can be applied almost all the time, although it can be quite hard to use when global variables or wide scopes are used (e.g. 1000 line for-loops in C). Comments are either obvious or they're lying. Why would you write something that the compiler will ignore eventually?

I first realized how hard is naming when I programmed in Forth. Amusingly, Forth is sort of a point-free type of language - everything happens on the stacks and there's no such thing as local variables, so a good chunk of the 'naming problem' goes away - but trying to squeeze a functionality in one or two lines can be difficult. The reason for this constrain is that I programmed mainly with a "block editor", a limited kind of editor that only 16 lines of 64 characters at a time. This wasn't an artificial constrain because I was working on a fully self-hosted hobby system, which had no file support (the [floppy] disk space was presented as a series of 1K blocks = 2 sectors = 80x16 bytes) and "block editors" are the easiest thing to implement in this case.

Despite the point-free nature of Forth, there's still the problem of naming functions ("words" in Forth lingo) and global variables. Programming in Forth is an interesting exercise because you quickly see the relationship between how you factor your code and how you name your "words". You discover by yourself many of the rules in the slides. But I find this is really the case when one uses the 64x16 block editor I mentioned. Using standard files and editors removes a lot of the constrains, but they also allow more sloppy coding (which may be a good thing if you have something better to do; e.g. you just need to write a throwaway script to get the job done).

In my experience you can spend a lot of time (re)factoring and (re)naming things. Sometimes it's valuable because e.g. it helps you understanding the problem, and sometimes you are just bikeshedding yourself.

When structuring code, elegance and efficiency always take top priority.

However, when naming, my philosophy is always clarity over elegance.

for example (in python):

     def reverseListAndAddOneToEachElement(input_list):

Ugly, but clear. I don't even need to write out the full definition you already know exactly what it does.

This seems like its trying to force advice for one domain to another when its not appropriate.

I disagree strongly with one or two of the rules. But an even bigger problem is that some (or even most) of the advice either has little value or doesn't really apply to programming. In english, shorter is better, but I'd much rather a longer class name that I can understand than one that's abbreviated to the point where I am forced to look up what its doing. A good rule of thumb that I try to follow is that for the most part, your code should be self explanatory (comments should cover the rest). We have these rules in programming for how to write variable names, and they're better than the ones in that slide. Another rule, that trumps any other is consistency. If you're working on a project that uses the passive voice (which I think works better for some cases) then use that. The nature of programming is different than natural language writing, and so it makes more sense that these rules that are trying to be transferred over are ill equipped to do so.

I mentioned that some of the things just don't make sense As an example, this was one of the slides, "when writing a novel a writer should create living people; people not characters. A character is a caricature." What does this mean? Its ironic that the slide preaches being short and to the point, and yet is bloated with abstract fluff.

I agree with everything except abbreviations, but to be honest, I think my worst habit it just trying to use words with the same number of characters for different variables so they align well with monospace font.

e.g.

    int num = 42;
    int acc = 0;

instead of;

    int n = 42;
    int acc = 0;

and it gets worse when things get complicated;

    vector<int> dist;  // stands for distances
    vector<int> excs;  // stands for excesses

Does anyone else have this problem?

Nice article. I loved the hieroglyph page; I think that functional programming failed for years as an engineering discipline because of the culture of that style of code.

My early days of OOP, I started keeping a thesaurus on my bookshelf at work. Probably went overboard on naming for a while, but reigned it in. (Every writer shudders at their first efforts. Hoo boy).

We would also hold short discussions about names for things (I don't see this in the article's list of tools: Involve other people in the names you are choosing. After all, they'll be using the code, too).

One Clojure style guide actually recommends[0] certain single-letter names for input parameters: x and y for numbers, n for an integer, s for a string, f (and g and h) for functions. These are used in the clojure.core namespace, and their use elsewhere is thus (presumably) justified by a general common understanding of their meanings.

[0] https://github.com/bbatsov/clojure-style-guide#naming

Thanks for the thorough write-up Peter! This pack of slides addresses "naming things" to depth that it could have been a little book...

I miss a few things though.

1. Short functions can use abbrevs; because I can keep track of them.

2. "text_correction_by_editor" might convey a lot more info then "edit"; especially in code where "edit" (and derivative) are heavily overloaded. For instance I can imagine "text_correction_by_user" also exists, or "text_reload_by_editor".

3. Then the Java'isms. E.g. AbstractWhateverSomethingManager. This is more part of the language, paradigm (OO w/ big love for design patterns) and type of money used to pay for development (enterprise money). Its verbose, deterministic and very "correct". Once you are used to the jargon you quickly know what they do, as they explicitly encode one of more patterns in their name.

This is a timely article because I was just talking to a friend of mine that works at Google and is about to start an internal project that will be written in Go.

I told him I'm not sure I'd ever fit into the Go community because the Go community seems to like variable names that are extremely short. For example:

  func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

I've even been "gently corrected" in #go-nuts on Freenode when I've shared code and I used "res" instead of "w" and "req" instead of "r" -- they told me my longer variable names wasted space and made it harder to read.

Perhaps my brain works different, but I find variable names that are actual words much easier to read.

Link to the video https://skillsmatter.com/skillscasts/5747-how-to-name-things...

I was always too ashamed to admit I use a thesaurus heavily while writing code. Glad I'm not alone.

I'm sure there is useful content in there, but holy crap is it ever obscured by most awful presentation.. Neither the slides nor the transcript are by any measure readable!

What did he mean by "never use passive when you can use the active (respect grammatical rules for identifiers)", on the slide 15?

I clicked through the first twenty or so slides, but really I find myself disagreeing completely with him. When you write don't use cliches but the meaning of AbstractConfigProxyFactory is clear and convey more information than anything else.

> It sounds like writing prose is as hard as writing code. Who knew?

Donald Knuth for one. He published Literate Programming in 1984. http://www-cs-faculty.stanford.edu/~uno/lp.html

I think you tend to develop naming habits after the environment you work with. C programmers follow Unix conventions, Java programmers create AbstractObjectFactoryFactory classes, and so on. It just feels natural.

My MacBook (with Chrome) does not like this site -- within 5 minutes of opening it and clicking through slides, it got very loud and hot and the battery went down by ~8%.

Is the George Orwell who i am thinking?

Nice write-up. But there's not a single slide about usability and how it affects naming.

If your library exposes 'getCurrentRuntimeContext' which is going to be used in every other line of user's code, name it 'ctx'.

It's ambiguous, but it saves the user 3 seconds per 2 lines of code.

As for the readability, when the reader encounteres 'ctx' for the third time (at line 6 of the source file) they will already know what it is supposed to mean by heart.