
On naming - lars512
http://quietlyamused.org/blog/2012/02/19/on-naming/
======
mekoka
This might be obvious to some, but I've literally only realized a few months
ago that when I write text, I will consult a thesaurus, whereas for some
reason I've neglected to do the same when I code. I would spend hours
agonizing on how to call a module, wondering if I won't need the same word
later for something else, or if it might be making things a bit ambiguous for
the next guy.

So I've started also using a thesaurus when I code and so far I'm happy with
the results. It's been helpful in accurately framing some of the hazier
concepts with interesting names. I also revisit the naming much less than I
use to, because I'm comforted with the notion that if I couldn't find a better
word with a thesaurus, then maybe there isn't an obvious one. I also now use
words that are clear, but that I so far neglected to include in my programming
vocabulary, because other more prevalent ones would jump in my mind and put a
shadow on my naming creativity.

So, if you need some help naming modules, functions, variables and db
entities, a thesaurus could help. Though, take care to not abuse of it.

~~~
panic
I do this too. Though my thesaurus doesn't always have the right technical
meaning of certain words.

I'd love to have a "programmer's thesaurus" with more detail on names that
appear frequently in code. For one of the two hard problems in CS, the art of
naming things has little reference material beyond raw source code.

------
j45
Naming things to be clear in the beginning, stay clear as the system grows, is
quite easily one of the hardest things in developing software.

Over generalized or specific names cause far more confusion and productivity
loss than we think.

So take the time to learn what you're working on and how it works at the micro
and macro level not only in the context of the application itself, but where
and how the application fits in it's ecosystem.

Learn the lingo that your software's ecosystem uses, instead of inventing, by
accident or purpose, your own clever and tricky rationalizations ending up in
even more confusing concepts and names describing the same things.

The purpose of naming is similar to the purpose of software; creating clarity
and empowerment, instead of more confusion and conceptual gymnastics.

------
cpeterso
For more rigorous naming, Eric Evans (in his excellent book _Domain-Driven
Design: Tackling Complexity in the Heart of Software_ ) recommends documenting
(and maintaining) your product's "Ubiquitous Language".

When developers (and the code), product managers, domain experts, and end
users all use different terminology, then cross-discipline communication
difficult and imprecise. A documented Ubiquitous Language enforces shared
terminology (and meaning) for all communication within the team and in the
code.

<http://domaindrivendesign.org/node/132>

------
raju
I am glad someone wrote this article - Now I know I can point it to my
colleagues who are often baffled at the amount of time I spend thinking about
names :)

I have found that when I can't find a good name for a method or a class, it's
because I haven't really thought the reason for the same through. This is
especially true for classes where I often realize that I am making the class
do too much, or too little.

This book, "Clean Code" by Robert Martin has it's second chapter dedicated to
naming things. A whole chapter! The book, alone for that chapter is worth the
money. If you haven't read it, I highly recommend it.

[http://www.amazon.com/Clean-Code-Handbook-Craftsmanship-
eboo...](http://www.amazon.com/Clean-Code-Handbook-Craftsmanship-
ebook/dp/B001GSTOAM)

~~~
lars512
Steve McConnell's book "Code Complete" was an eye-opener for me. It also has a
whole chapter on variable naming, and is worth a read.

[http://www.amazon.com/Code-Complete-Practical-Handbook-
Const...](http://www.amazon.com/Code-Complete-Practical-Handbook-
Construction/dp/0735619670/ref=sr_1_1?ie=UTF8&qid=1329769782&sr=8-1)

------
rplnt
The first quote in the article; I thought it went like this:

 _There are only two hard things in Computer Science: cache invalidation,
naming things and off-by-one errors._

~~~
caf
That version is just a well-known play on the original.

------
dhotson
I find that thinking about good names for things can help guide you to design
better code.

As Lars mentioned—if something is hard to name, it's probably because the
thing you're naming isn't very clearly defined, is a bad/mixed metaphor, or is
just plain hard to understand.

And if all else fails, there's always <http://www.classnamer.com/> ;-)

------
medopal
My colleagues (developers) laugh when I pause few seconds to think about a
proper name for a Java method. But I take it seriously, finding a class or
method with proper name is way easier than an ambiguous name> Even a proper
name with misspelling is considered bad in my dictionary.

Once in an interview, I asked the guy to write some code, he used variable
names like "int ttttt=1;". I never saw him again!!

------
Detrus
I think this problem comes up from the somewhat obsolete linear text nature of
code. Instead of particular perfect names, we could be using tags.
AbstractSingletonFactory is three tags. In some contexts I'd like to know it's
a factory, in others I don't.

The bigger problem is we haven't moved on from the simple text representation
of code. And this overly simple tool, text, is influencing the way we're
thinking here. The Humble Programmer phenomenon in action.

------
gmoes
I agree, naming is important and often overlooked, check out this quote by
Josh Bloch: [http://www.elegantcoding.com/2011/07/software-frameworks-
res...](http://www.elegantcoding.com/2011/07/software-frameworks-resistance-
isnt.html#Names)

------
jmonegro
What I like to do is add a variables.txt file to the root of the project as a
sort of legend for any unconventional variables I have to name. I try to stay
as relevant as possible, but sometimes 'anospic' is better than
'average_numbers_picked'.

Good or bad, it works.

~~~
danssig
If you use a decent IDE, having longer variable names is nearly no cost.

~~~
snprbob86
I don't buy this argument, but you're in good company holding this belief.

Generally, I find that long names fall into three categories:

1) refactoring opportunities

Use more namespaces, write smaller functions, embrace lexical scoping, etc.
You don't need to call something a _foo-bar-frobber_ when it's being used in
the _foo-bar_ context, just call it a _frobber_.

2) line noise

If you're only using the _frobber_ within a two line function, and it is
initialized via _create-frobber_ , do you really need to spell it out? _f_ or
_x_ will do. If your function grows, rename the variable. Or refactor!

3) an absentee synonym

Maybe you've got a _monster-which-attempts-to-defeat-player_ , when you really
need a _baddie_. Or maybe the word you need doesn't exist yet? It's rare, but
sometimes you really do need to invent or repurpose a word.

...

I always feel dirty when I have a long variable name. pg writes about this in
On Lisp: long names _feel heavier_. They might be super cheap to call, but
because the name is long, you're less likely to call it.

Furthermore, I much rather adhere to a line length limit, as I find wrapping
lines far harder to read than lines with short variable names. Long names
makes this harder.

All that said, I almost _never_ use abbreviations other than standin variables
like a single letter. The only exception to this is well known abbreviations,
like for your most commonly used utility functions or for objects which are
extremely common in your problem domain. Such a set of abbreviations becomes a
part of the language you share between your compiler and your team.

~~~
lemming
_f or x will do. If your function grows, rename the variable._

Why would you just not give it a reasonable name to begin with? Why not call
your variable _frobber_? The only possible reason for not doing so is that
you're using an editor that makes you type it every single time. I insist that
calling your Frobber variable _frobber_ is strictly easier to understand than
_f_ or _x_. Why not _t_? Or _sdfsdg_? None of them make any sense to someone
reading the code, and it increases the amount the reader of the code has to
keep in their short-term memory, making it more challenging to understand.

 _pg writes about this in On Lisp: long names feel heavier. They might be
super cheap to call, but because the name is long, you're less likely to call
it._

Even if pg wrote it this is patently absurd, and it's endemic in lisp code
which contributes greatly to the famously write-only nature of lisp. Again, if
you're using a decent editor, there is no reason to call your UserDetails
object anything but _user-details_ (or maybe _details_ if you're in a context
only relating to users).

~~~
snprbob86
> The only possible reason for not doing so is that you're using an editor
> that makes you type it every single time.

Here's some C:

    
    
        for (int player_index = 0; player_index < players.length; player_index++) {
          int rank = player_index + 1;
          render_score(rank, players[player_index].name);
        }
    

Blah. So much for the brain to parse!

    
    
        for (int p = 0; p < players.length; p++) {
          int rank = p + 1;
          render_score(rank, players[p].name);
        }
    

I find that much, much easier to parse in my head. The definition of p is
available without any backtracking. The word "player" appears five fewer
times, reducing confusion with the players array. This is a _small_ case.

If this code were to start to grow, and the definition of p and its usages
start to grow appart, it's trivial to replace.... but it's probably better for
you to refactor.

~~~
lemming
That's kind of a pathological case you have there - I don't think many people
would argue that loop indices should have long variable names. None of the
examples in your post above were loop variables, and what I see a lot of in
lisp code is using _ps_ for _players_ , for example. In your example you've
used pretty sensible names for _players_ , _rank_ and _render_score_ \- why
not _ps_ , _r_ and _rs_ respectively?

~~~
snprbob86
> why not ps, r and rs respectively?

Um... Because that would be hard to read?

I'm advocating using full words in general, avoiding long variables (multi-
word phrases, adjectives, contextualization, etc), and not being afraid of
short variables names if they help, rather than hurt readability.

There are plenty of cases where short names are totally fine. If you've got a
module full of string utilities and every single function takes a first
argument of type String, why not just call it "s"? Everyone will figure it out
in seconds and it will save the mental overhead of differentiating "String"
and "string". when that does come up.

Things like that; I'm saying use your judgement.

------
tariq
cool, and here i thought i was alone in needing to take time to name things
correctly.

had to name a variable earlier this week and even broke out the thesaurus.
best i could muster was years_experienced_absolute :/

~~~
akkartik
Sometimes when I have trouble coming up with a good name it's a sign that I
need to rethink the surrounding code as well.

Since naming is hard, I try to minimize the number of names I create. I think
the number of names in a codebase is a measure of complexity.

~~~
snprbob86
Names are also critical to understanding.

It's very similar to the phenomenon of notation (including maths, sciences,
and, yes, programming languages themselves):

"By relieving the brain of all unnecessary work, a good notation sets it free
to concentrate on more advanced problems, and, in effect, increases the mental
power of the race." -- P Davis and R Hersh The Mathematical Experience (Boston
1981).

I know that my team spends an inordinate amount of time debatting the names of
concepts. We've found that, since we're trying to build something unique,
there aren't always words for the concepts we're building. Worse yet, there
are words that are close, but not quite right! It's extremely difficult to
write any code before everyone can hear a word and reach a common mental
image. I've found that if you get the right names, the code is so much easier
to write and reason about.

------
vrode
Choosing the right metaphor in terms of OOP is equally important as well as
the understanding the word's meaning and the implication of alternative
meanings.

------
rgc4
Seriously, he suggests using i as a variable? I couldn't take him seriously
after that.

~~~
dhotson
It's an example of using a language's idioms. If you use i in a loop, there's
no need to explain yourself since there's a common understanding as to what
this means.

~~~
rgc4
If you use i, you're a bad programmer. You can't search for the variable name,
you can't make sure it is used correctly everywhere. You're a bad person.

