
How to name things in programming - colinprince
http://www.slideshare.net/mobile/pirhilton/how-to-name-things-the-hardest-problem-in-programming
======
jacquesm
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...

~~~
msellout
Correspondingly, some objects don't need names at all.

    
    
        sorted(pairs, key=lambda p: p[1])
    

Though in that case you might prefer using the operator module.

    
    
        sorted(pairs, key=operator.itemgetter(1))
    

The aspect of Ruby that frustrates me the most is over-use of anonymous blocks
when a good name would help me enormously.

~~~
techiferous
> The aspect of Ruby that frustrates me the most is over-use of anonymous
> blocks when a good name would help me enormously.

Ruby gives you enough tools to write code clearly with good names if you want
to. I think your complaint might be more about the particular style of Ruby a
certain programmer wrote than the language itself.

~~~
msellout
Correct, though I find that a language is more about the community and culture
than the syntax itself.

------
dkersten
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).

~~~
jkire
I agree, though there is a difference between being able to explain something
and naming it. I've been known to forget the word "door", but I could quite
happily explain how it worked.

~~~
ignoramous
Might be an outlier, IMO.

And I guess this is exactly why author wants programmers to learn from the
masters of spoken langauges-- ability to use the right word(s) to explain the
concept/abstraction/property/behaviour/type.

If one is unsure about how something works, then more often than not one would
end up naming the thing wrong. By far and large, the most frustrating thing
I've come across during code-reviews is generic names assigned to vars like
'buffer', 'arrays', 'queues' and so on... and SQL table names that have no
relevance to the data being stored in them. It is a constant struggle to read
and reason with such constructs. So if you know how something works, you are
oblidged to name it approp.

Douglas Crockford in his 'JS: The Better Parts' talk at JSConf 2014 spoke
about three responsibilities a developer must have:

1\. Make life of people using the software better and to not frustrate them,
humiliate them, hurt them, confuse them.

2\. Make life of people maintaining/developing the software better . To not
check-in cruft, bloat, and errors. Write the best code, and to not make
anything worse.

3\. Make life of people managing the business/development easier.

~~~
bshimmin
What does "Make life of" mean? As a native English speaker, I don't understand
it; I presume it means "Make life better for", though the closest we have in
English is probably "Make light of", which means something completely
different (and is slightly funny in this context).

~~~
DougWebb
He means "Make _the_ life of people..." in each case. The phrasing without
"the" sounds to me like Powerpoint-Speak... leaving out minor words in order
to fit more bullets onto a slide. Those minor words are usually grammatically
necessary, but in the context of a slide presentation the presenter's verbal
part of the presentation clarifies ambiguities in the visual part.

~~~
bshimmin
Ah, thank you, you must be right. "Make life better for people..." would in
each case have been grammatical and slightly more comprehensible to me!

------
cessor
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?

~~~
falcolas
> Why would you write something that the compiler will ignore eventually?

Because your real target for your code is not the compiler, it's your co-
workers, who will have to go back and read and modify your code. Plus, they
may not be able to contact you with questions about your code.

A single well written comment can save your co-workers from having to read a
hundred lines of test code (and correspondingly, test code boilerplate). Why
not give them that kindness?

> Comments are either obvious or they're lying.

This argument only applies to poor comments, which were not maintained
alongside the code. If you just remember that the audience your code was
written for is not the compiler, it makes more sense.

~~~
enraged_camel
>>Because your real target for your code is not the compiler, it's your co-
workers, who will have to go back and read and modify your code.

Your co-workers _and_ your future self. :)

~~~
thesimpsons1022
in rare cases: your customer

------
astrobe_
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.

------
crimsonalucard
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.

~~~
tmikaeld
I like the logic of this, but it goes against all books that i've read to keep
it short. Why do we need to keep it short?

~~~
squidbidness
In this case it's a symptom of poor cohesion and separation of concerns. If
you find you're having to give very long names for things, it's worth looking
for a way to decompose it into separate things that each do one simple thing.
Then more than likely writing the code that composes the separate objects with
the right operations will be the perfect substitute for the long name, and it
will also be easier to maintain, since you won't have to update both the
variable name and the logic that uses it; rewriting the actual expression or
logic where it is used will take care of both tasks in one. This is what I
usually take from the principle of letting the code itself be your
documentation, where reasonable.

~~~
crimsonalucard
Who says reverseListAndAddOneToEachElement isn't defined via the composition
of smaller "separate things that each do one simple thing?" The naming
convention still stands as it is not a "symptom of poor cohesion and
separation of concerns."

------
forrest92
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.

~~~
nandemo
This. Some of the advice only works out of context, for example:

> What's an _appointment_list_? A _calendar_

No. Chances are that "appointment" is already a thing in your domain language
-- the language you'd use to talk to your customers and stakeholders -- and so
_appointment_list_ is a much clearer name than _calendar_ , as long as we make
the reasonable assumption that it names a collection of appointments.

~~~
plorkyeran
None of the examples of just using a single word seemed like improvements to
me. appointment_list to calendar was by far the worst—calendar can mean a lot
of things, and a list of appointments was not even the first thing that comes
to mind for me—but in all of the cases the single word meant something
significantly different than the thing it was replacing.

------
g1236627
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?

~~~
ttty

        int n   = 42;
        int acc = 0;
    

Fixed

Edit: Install
[http://wbond.net/sublime_packages/alignment](http://wbond.net/sublime_packages/alignment)
and add this key binding `{ "keys": ["ctrl+shift+a"], "command": "alignment"
}`.

~~~
jacquesm
That's actually right against the style guideline of many projects which tell
you explicitly not to do this but to simply put the = sign and value right
after the variable name and be done with it. Lining them up serves no purpose
and does not in fact make the code easier to read.

~~~
ttty
To be honest it actually makes code cleaner and therefore easier to read. It's
like design have you heard about grid? this is the same thing. Your eyes have
to flow the lines. If not everything seems a mess.

~~~
SamReidHughes
> To be honest it actually makes code cleaner and therefore easier to read.

It does not logically follow from the code being "cleaner" that it is easier
to read. Having to scan across a field of whitespace to get to the number
makes it harder to read and easier to make mistakes. Having the indentation of
the number be unrelated to the length of the variable name adds another aspect
that makes it harder to read and easier to make mistakes.

It's also harder to edit, which makes you do fewer edits that make the code
materially better.

~~~
wetmore
It depends on context. For example, here is a function from a project I'm
working on:

    
    
        parseModifier : String -> Outcome Modifier
        parseModifier s = case s of
          "shift"   -> Ok Shift
          "ctrl"    -> Ok Ctrl
          "alt"     -> Ok Alt
          "meta"    -> Ok Meta
          "command" -> Ok Meta
          "windows" -> Ok Meta
          x         -> Err <| "Unknown modifier: " ++ x
    

I find it easier to read as is rather than if I dropped the alignment:

    
    
        parseModifier : String -> Outcome Modifier
        parseModifier s = case s of
          "shift" -> Ok Shift
          "ctrl" -> Ok Ctrl
          "alt" -> Ok Alt
          "meta" -> Ok Meta
          "command" -> Ok Meta
          "windows" -> Ok Meta
          x -> Err <| "Unknown modifier: " ++ x
    

As developers we spend more time reading code than editing it. Optimizing for
readability seems like a better goal than optimizing for edit speed. Besides,
most editors have functionality to align code. When I am looking over a file,
the second example looks like a jumble of words to me, while the aligned
version seems easier to parse (ha).

~~~
mercurial
I agree that unaligned switches/pattern matches are bad (and in fact, there is
an utility for OCaml which will nicely indent your pattern matches).

------
kabdib
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).

~~~
ericssmith
"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."

I don't quite follow your observation, but if you are suggesting that this
function would be better with verbose, Englishy naming, I think you are
mistaken. Quite the opposite, the parametrically is better illustrated with
hieroglyphs.

Regarding failing "for years as an engineering discipline", are you suggesting
that imperative programming was "successful" because of the reliance on using
naming to communicate intent in the midst of rampant state mutation and
unbridled complexity?

------
dghf
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](https://github.com/bbatsov/clojure-style-guide#naming)

~~~
MadcapJake
Functional programming languages use single-letter parameter names as a tool
to help condense functions and allow easy parsing. This is largely due to
their desire to emulate mathematical formulae.

Interestingly, functional programming leads to a different naming custom that
this presentation didn't really cover. To write "functionally" you want to
have pure single-purpose functions and the name is supposed to describe
_exactly_ what the function does. If you can't write a short enough function
name then your function is probably too long and should be broken up into
functions that _can_ be given concise names.

Another interesting functional programming naming custom is that a function
that transforms data (fully FP) should describe the final result rather than
the action of changing it. So if you transform a string to json, the function
should be simply called `json` rather than `string-to-json` or `json-parser`.
This is because when reading the code you can clearly see that the string is
now json (it can almost look like a type). Of course, if that function does
_anything else_ , then naming it `json` is wrong but the function is also
breaking away from being pure and single-purpose.

~~~
tjradcliffe
Actual mathematical functions have some of the most useless, non-descriptive
or vaguely metaphorical names going, so I'm not sure promoting an isomorophism
with FP is a good thing. Examples: "bessel", "spherical_harmonic", "delta",
"zeta"... Math is hard, and the terseness of mathematical notational
conventions is one of the things that makes it so. Names that carry meaning
with them are an aid to the naive user, and that is a good thing.

Secondly, naming a function "json" requires the user read the code or the
comments to figure out what it does, and blocks the user of the name for
anything else that returns json. Suppose rather than a string you have a list
that you need translated to json... what do you name the function?

There are three levels of documenting code: naming, comments, and the code
itself. Function names should be chosen such that other developers can
reasonably guess at a glance what the function does, because the two most
comon use-cases for names are:

1) reading someone else's code, where digging in to find out what "json" does
is orders of magnitude more work than reading "json_from_string"

and

2) figuring out how to do something in a given codebase, where skimming over a
list of function names and picking out one or two that look likely for deeper
investigation is orders of magnitude faster than reading the docs or the code
for every function to find out which obscurely-named function does the job you
want.

Longer, more fully descriptive names aid the user in the excecution of these
use cases.

~~~
JadeNB
> Secondly, naming a function "json" requires the user read the code or the
> comments to figure out what it does, and blocks the user of the name for
> anything else that returns json. Suppose rather than a string you have a
> list that you need translated to json... what do you name the function?

`json` --polymorphic languages make naming easy!

------
cies
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.

~~~
anon4
Java class names are like Haskell function types. In fact, there are libraries
that can autogenerate implementations for database logic by the name of the
interface and methods alone, much like you can guess what the function does
just by the types it operates on.

~~~
cies
> Java class names are like Haskell function types.

They are conventions (like Haskell types) but they lack the laws.

------
Teckla
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.

~~~
adiabatty
The thing about the arguments to an http.HandlerFunc is that everyone uses w
and r for the argument names because everyone else does. Additionally, if
you're writing a http.HandlerFunc, you're likely repeatedly exposed to a bunch
of other http.HandlerFuncs in standard library code and gorilla/mux, all of
which use w and r.

Because of this, anyone who's been wrangling HandlerFuncs for more than a few
days tends to converge on w and r. At this point it's no more a problem than
using short variables like d for distance or r for radius in math formulas.

As an aside, I have a file open right now with a struct member called
"TentativeSpacesPerIndent int"; I'm not worried — yet — about how ungainly
long it is because I'm still trying to figure out what indices I need to keep
track of, and the last thing I want to do is confuse myself into using one
type of index when I need another, or perhaps I need to track of something
else entirely. On the other hand, I have

    
    
      func NewScanner(bs []byte) Scanner
    

and all the thought I put into the name of the argument is "if a single byte
should be a 'b', what should a slice of bytes be? 'bs'." That seems to be
sufficient length for a five-line function.

------
nahname
Link to the video [https://skillsmatter.com/skillscasts/5747-how-to-name-
things...](https://skillsmatter.com/skillscasts/5747-how-to-name-things-the-
solution-to-the-hardest-problem-in-programming)

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

------
btbuildem
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!

~~~
wetmore
Really? I found the slides very readable.

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

~~~
asmithmd1
passive:

He was told by a doctor to take a pill

active:

The doctor told him to take a pill

~~~
stockkid
He provides examples `class PlanEvents`, `class EventPlanner`, `class
Scheduler`. To me, they all seem to be active. Any thoughts?

~~~
throwaway41597
I also found the examples confusing. What I got is they are all nouns (respect
the grammar rule of having nouns for class names) but `PlanEvents` reads like
data that is going to be processed (passive) whereas `EventPlanner` and
`Scheduler` are concepts that process data (active). They have a verb: "plan"
and "schedule".

~~~
stockkid
Thanks for clarification. I think I disagree with the author here. In my
experiences, it's sometimes awkward to use '-er,' '-or' suffixes to turn name
into concepts that process data (active) e.g. JobUpserter, ...

------
tomjen3
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.

~~~
MichaelBurge
An AbstractConfigProxyFactory is a base class or interface for creating
factory classes that return configuration objects(possibly lazily - through a
proxy object - in order to avoid unnecessary disk IO or network traffic).

Two cases where you might want different factory classes(and hence need a
common interface or base) are a factory for 'production' code and a factory
that only generates mock objects for unit tests.

Having spent 5 minutes trying to understand what this class might do, I
disagree with your claim that the name is clear.

------
brianpan
> 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](http://www-cs-
faculty.stanford.edu/~uno/lp.html)

------
golergka
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.

------
throwaway39202
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%.

~~~
watson
For a long time I just used Chrome - because why not? It's an awesome browser,
especially when you are a web developer. But I was always annoyed about the
fan on my MacBook Air mid 2011 spinning all the time - but I didn't connect
the dots. At some point though it must have dawned on me and I tried an
experiment where I switched 100% to Safari. Now my fan NEVER spins and I get
up to two hours more battery life out of my MacBook Air. (yes I know it's a
really bad browser on almost all counts - but they do know how to code in an
energy efficient way)

------
yyhhsj0521
Is the George Orwell who i am thinking?

~~~
icebraining
I don't know who you're thinking of, but this George Orwell is the author of
1984, Animal Farm, Homage to Catalonia, etc.

------
rumcajz
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.

~~~
kabouseng
I'm not so sure that is good advice, and I come from C programming so we love
to do that.

With autocompletion in most code editors saving the user typing time is not a
valid argument anymore, and I would rather prefer comprehensible if slightly
more verbose code than accronyms everywhere.

What is obviously ctx -> getCurrentRuntimeContext for you is completely
foreign to the next guy. And sometimes you don't spend a large amount of time
in a specific part of a code base, such as when debugging and then figuring
out what ctx means is a real PITA.

~~~
walshemj
You are assuming that every one can recall 25+ letter names - dyslectics have
problems with this sort of short term memory.

~~~
Retra
That is a very weak argument. Is there anything that suggests letter count is
a barrier to dyslexics, and not, say, word count or number of obscure
abbreviations?

~~~
walshemj
Yes short term memory tests are one of the primary diagnostic tests for
dyslexia. Ie how many consecutive numbers/letters you can recall.

Long Names like SomeRealyLongNameFunctionThing and
SomeRealySimialrLongFunctionNameThing are both hard to work with and confusing
to me.

